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JAVA AND LIGHTWEIGHT COMPONENTS 22 
by David K. Perelman-Hall 

JDK 1.1 lightweight components let you give programs exactly the same look-and-feel— no matter 

which platform hosts the VM. To examine lightweight component development, David presents his 
dph.awt lightweight package. 


A JAVA APPLET SEARCH ENGINE 32 
by Tim Kientzle 

Most search engines are designed for web sites. The Java search engine Tim presents here, however, 

was designed for use on HIML-based CD-ROMs. The differences might surprise you. 


THE JAVA 2D API Ag 
by Bill Loeb 

The Java 2D API is a set of functions that is a much more flexible and full-featured rendering package 
than previous versions of the Abstract Windowing Toolkit (AWT). It provides enhanced graphics, text, 

and image handling, supports color definition and composition, and is extensible. 


WRITING JAVABEAN PROPERTY EDITORS 52 
by Morgan Kinne 

JavaBeans are reusable software components that can be manipulated by visual programming tools. 
Morgan shows how you build property editors, focusing on the relationships between the visual tool, 
property editor, and bean. 


PERSONALJAVA AND INFORMATION APPLIANCES, PART II 64 
by Jaison Dolvane and Kumanan Yogaratnam 

In the second installment of this two-part article, Jaison and Kumanan examine the hardware 
requirements for PersonalJava applications, discuss the embedded operating systems that support 
PersonalJava, and put PersonalJava and Kalos Expresso to work by developing a phone directory 
application for a web-phone appliance. 


JPERL: ACCESSING PERL FROM JAVA 103 
by S. Balamurugan 

The Jperl package, written in C++, provides an interface to Perl from Java, and Jperl’s APIs also make 
accessing Perl from C++ simple. This article outlines the capabilities of Jperl and explores its features. 


Cover photography by Pat Johnson Studios. 


EMBEDDED SYSTEMS 


JAVA CARD APPLICATION DEVELOPMENT 12 
by Darryl Barnes 

Although the Java Card specification is a subset of Java designed for smart card applications, the 
Java Card API has little in common with the standard Java API. Darryl discusses Java Card and 
presents a typical smart card applet. 


INTERNET PROGRAMMING 


CREATING SIGNED, PERSISTENT JAVA APPLETS 82 
by Paul Brigner 


Both Netscape and Microsoft have facilities for signed, persistent applet deployment that extends 
the Java security framework. This should come as no surprise; however, that doesn’t mean that you 
use these facilities the same way. 
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COMPARING WFC AND JFC 0 
by David M. Johnson 

David compares Microsoft's Windows Foundation Classes (WFC) with Sun’s Java 
Foundation Classes (JFC) framework by developing an Internet Relay Chat (IRC) 
chat-client called “Relay.” 


DESIGN BY INTERFACE % 
by Robb Shecter 

Robb presents step-by-step instructions for making applications both reusable and 
independent using a technique called “design by interface” and the 

NetComponents class library from ORO. 
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PROGRAMMING PARADIGMS 107 
by Michael Swaine 

Carl Sassenrath is a rebel with a cause— and that cause is Rebol, a messaging- 

based programming language designed for networks and the Internet. 


C PROGRAMMING HI 
by Al Stevens 

Quincy 99 goes into testing, as Al prepares it for use for developing D-Flat 2000, a 
Win32 application framework that uses Standard C++ features, 


JAVA Q&A 115 
by Dave Angel and Andy Wilson 

Dave and Andy show how you can store a Java app in a self- executing encrypted 

file. In doing so, they present CodePacker, a custom loader that is both easy to 
install— it’s self-extracting— and secure. 


ALGORITHM ALLEY 123 
by Andrew Colin 

The analytic hierarchy process (AHP) is a decision-making tool reducing complex 
decisions to a series of comparisons and rankings. The results are then combined 

to give a single, unequivocal result. 


DR. ECCO’S OMNIHEURIST CORNER 13] 
by Dennis E. Shasha 

Dr. Ecco and Liane dig up some dirt about archeologists in this month’s 
installment. 


PROGRAMMER’S BOOKSHELF 135 
by Gregory V. Wilson 

Greg looks at a number of books this month, including The Essence of SOL, by 

David Rozenshtein, The Perl Cookbook, by Tom Christiansen and Nathan 

Torkington, High Performance Computing, Second Edition, by Kevin Dowd and 
Charles Severance, JavaScript for the World Wide Web, Second Edition, by Tom 
Negrino and Dori Smith, AntiPatterns, by William J. Brown, Raphael C. Malveau, 

Hays W. McCormick II], and Thomas J. Mowbray, and Beginning Object-Oriented 
Analysis and Design with C++, by Jesse Liberty. 
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EDITORIAL 





Open Season 


Bill Gates say to a bedraggled Richard Stallman, “Yep pardner, you’re right. Free software is 

sweeter than a stolen kiss behind the revival tent.” Of course, the chances of that happening 
are at least as good as Gates donating tens of millions of dollars to fight childhood diseases or 
build public libraries. 

In all likelihood, the notion of free software, open source, or whatever it’s now called has stuck 
in Gates’ craw since DDJ published the first line of Tiny BASIC code nearly 25 years ago. Gates, 
who had just formed a company called “Micro-Soft” to sell his version of BASIC for $500, couldn’t 
understand why anyone would want to compete with him by giving away better software for 
free. But then, Gates obviously saw something the rest of us didn’t. Witness that, to the best of 
my knowledge, no past or present member of the DDJ staff is a billionaire. 

Over the years, free software/open source continued to be an itch that Gates couldn’t scratch. 
In one of the great ironies of computer history, however, it wasn’t until Microsoft had more or 
less crushed its competition in the system software and tool arenas that free software/open source 
went from being an irritating bug bite to a full-body rash. When tool options more or less became 
Microsoft or nothing, developers moved to GNU in two shakes of a lamb’s tail. And when 
Windows became the dominant desktop operating system, Linux stood as one of the few 
alternatives. In ignoring free software, Microsoft failed to realize (or refused to acknowledge) that 
“open source”— broadly defined as the free flow of information— is absolutely fundamental to 
scientific advancement. Has been in the past, will be in the future. It isn’t that developers want 
inexpensive tools (Stallman reminds us that it’s “free” as in “free speech,” not “free beer”), but that 
they want to control the tools, instead of the other way around. 

Putting its Justice Department problems aside, the result of worshipping proprietary 
protocols to meet short-term financial goals probably means Microsoft will evolve into a new 
kind of company in the future— one that embraces the concept of open source in one form 
or another. This doesn’t necessarily mean that Microsoft will, say, release the source to NT or 
send out the obligatory press announcement stating it is an open-source company. No, 
embracing the open-source concept involves more than source code. It is a way of thinking, 
of doing business, of living life. 

Demonstrating that it isn’t entirely asleep at the switch, Microsoft recognized the need for 
change and began experimenting with different business schemes a while back. The company’s 
move to subscriptions and similar variations on licensing themes underscore this. In fact, changes 
in licensing strategies were at the heart of the “Halloween Document” (http://www.opensource 
.org/halloween1.html), a supposedly internal Microsoft memo that analyzed how the company’s 
business/development models related to the free software/open source movement. By hook or 
crook, the memo found its way to the Internet in November 1998, and the resulting furor 
galvanized open-source champions. 

For that matter, Microsoft (for all of the wrong reasons and to the consternation of its 
customers) already adheres to one of the basic tenets of the open-source movement— release 
early, release often. The company is infamous for releasing software way before it’s ready, then 
fixing bugs as they’re reported and adding features as they’re requested. 

Underestimating Microsoft's ability to adapt to a business model based on open source is a 
mistake. If nothing else, Microsoft has proven over and over it is intelligent and resilient, and can 
learn from both its errors and those of others. Look how quickly it became an “Internet” 
company. 

So, what will this emerging business/development model look like? I don’t know, but Tim 
OReilly raises some possibilities in a lengthy essay entitled “The Open-Source Revolution” in 
Release 1.0 (see http://www.edventure.com/release1/1198.htm). 

Although some open-source advocates are more antiMicrosoft than pro anything, the open- 
source movement isn’t just about Microsoft. It is about establishing and adhering to a model for 
moving forward and realizing the promise of science in general, and computing in particular. In 
short, what the open-source movement is all about is passion, invention, and innovation. And 
hey, if you can make a buck at the same time, that’s cool, too. 


Sore ltickn 


Jonathan Erickson 
editor-in-chief 
jerickson@ddj.com 


[: be willing to bet that any number of people would buy tickets to hear a buttoned-down 
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LETTERS 








And the Winner is... 


Dear DDJ, 

Regarding Wesley Stout’s Y2K patent ap- 
plication mentioned in “News and Views” 
(DDJ, October 1998): This gets an award 
for the “U.S. stupid patent department” if 
it gets a patent! Not that it’s a silly idea, 
it's just that a DDDCYY format date has 
been around for at least 20 years. I worked 
on life insurance systems (which have al- 
ways had to handle dates beyond 2000, 
and before 1900) that had this format in 
1982, and they were already old systems! 
I personally have probably written >1000 
modules using this format, not to mention 
having processed a few billion dates in 
that format... 

I know the U.S. patent department will 
patent anything, but this (if possible) is 
creating a new area of silliness. 

Ian Quick 

ianq@ozemail.com.au 


More on Win32 Debugging 

Dear DDJ, 

Fritz Lowrey’s article “Examining the 
Win32 Debug API” (DDJ, November 1998) 
describes how to grab OutputDebugString 
text with the specific purpose of debug- 
ging NT services. Although this approach 
works, it is overkill. Since v3.51 NT has 
provided ODS text as a memory-mapped 
file and manual reset event pair so that it 
could be viewed w/o running under a de- 
bugger. This technique works with ser- 
vices, as well as any other type of pro- 
cess or application. 

For a discussion of how this works, see 
my article “A DBWin32 Debugger for Win- 
dows” (C/C++ Users Journal, October 
1996). You also can grab the latest ver- 
sion of DBWin32 (w/ source) at http:// 
www.halcyon.com/ast/swdev.htm. 

Andrew Tucker 

ast@halcyon.com 


Quicksort Improvements 

Dear DDJ, 

Jon Bentley and Robert Sedgewick’s 
November 1998 “Algorithm Alley” presents 
improvements to the standard Quicksort 


10 


algorithm. Another surprisingly useful and 
easy to code variant of the standard Quick- 
sort algorithm to mix a simple bubble sort 
into it. As the left and right pointers move 
toward the center of the array, have them 
do pairwise swaps with the array position 
they previously read and the one to which 
they are moving. That is, instead of simply 
using /ft++, use swaptalYft] allfi++); Ifi++} 
and rgt -- becomes fswap(alrgt], alrgt--) in 
their respective loops. This assumes that 
swap() will do the proper testing. 

Because Quicksort takes advantage of 
any existing sort order, this little trick can 
make each succeeding recursive call to a 
partition run faster than it would have with- 
out the sort. An even better improvement 
can be had if the hardware supports a pait- 
wise-exchange function to allow us to build 
a specialized version of swap). 

Joe Celko 

71062.1056@compuserve.com 


Ab Hab! 
Dear DDJ, 
Regarding the Microsoft’s AARD code de- 
scribed in “Examining the Windows AARD 
Detection Code,” by Andrew Schulman 
(DDJ, September 1993): This cinches it for 
me and maybe for others as to Microsoft’s 
intentions. The error code #4D53 seemed 
suspicious in the alphabetic ASCII region 
(when treated as hex character codes). 
Sure enough, 4D is “M” and 53 is “S.” A 
coincidence? I think not. 
Todd Stephan 
TStephan@genscan.com 


WinCE Terminology 

Dear DDJ, 

I am writing in response to James Wilson’s 
article “Windows CE Device Driver De- 
velopment, Part I” (DDJ, October 1998). 
As I work at Microsoft documenting de- 
vice driver development for Windows CE, 
I was very interested to see the article. I 
was quite pleased with the overall mes- 
sage conveyed in the article, and I look 
forward to reading Part II. 

Nevertheless, I feel that a clarification 
is in order. James spends a fair amount of 
space (on page 72) discussing the mean- 
ing of the terms “installable device driv- 
er” and “built-in device driver” as they re- 
late to categories of device drivers 
supported within Windows CE. That at- 
tention is certainly warranted, as those 
terms were indeed confusing. However, 
we have changed them in version 2.x of 
Windows CE, for reasons discussed later. 
The new terms are “stream interface driv- 
er” and “native driver,” respectively. I re- 
alize that in the world of magazine pub- 
lishing there can often be substantial lead 
times between when articles are written 
and when they are published, so it is not 


surprising that James wrote his article in 
part on the basis of documentation that 
has since changed. 

It is worthwhile to explain some of 
the history behind this decision. Much 
of the early Windows CE documenta- 
tion was associated with the first Win- 
dows CE device, the Handheld PC 
(H/PC). That platform, although pro- 
duced in several slightly different vari- 
eties by different manufacturers, was 
well defined in the sense that all H/PCs 
had a common set of operating-system 
services, and all contained a common 
core set of peripheral devices. Those 
similarities meant that it made a great 
deal of sense for each class of device 
driver, corresponding to the classes of 
built-in devices common to all H/PCs, 
to have a custom interface to other parts 
of the Windows CE operating system — 
primarily Graphics, Windowing, and 
Events Subsystems (GWES). By doing 
so, we were able to standardize the be- 
havior of those devices and provide a 
common code-base for H/PC manufac- 
turers to work from. Recognizing that 
there was a need to add arbitrary new 
device drivers, both for third-party hard- 
ware vendors and for addition hardware 
added by H/PC manufacturers to their 
own Windows CE products, Microsoft 
also implemented the “installable” device- 
driver model as James discussed. Thus, in 
the Windows CE 1.0 timeframe, there was 
an excellent correspondence between the 
term “built-in device driver” and the de- 
vices that were actually built into the first 
generation H/PCs. Similarly, there was 
good correlation between the term “in- 
stallable device driver” and any after-mar- 
ket or additional devices that could be 
connected to an H/PC. 

As Windows CE evolved toward ver- 
sion 2.x, however, many of the drivers 
included in typical Windows CE prod- 
ucts changed to use the “installable” driv- 
er interface rather than their own spe- 
cial purpose “built-in” interfaces to 
GWES. Display drivers who wanted to 
manufacture PC Card-based display 
adapters to write drivers for their devices 
are a prime example of this. Such 
changes took place for several other 
classes of device drivers as well. Thus, 
the terms “installable driver” and “built- 
in” driver ceased to have a good corre- 
lation between the interface model used 
by the drivers themselves, and exactly 
the sort of issue that James discussed in 
his article resulted. 

Thus, for the current generation of Win- 
dows CE documentation, the terms have 
been changed. Now the terms to describe 
Windows CE device drivers are related to 
the types of interface between the drivers 
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(continued from page 10) 

and the rest of the Windows CE operat- 
ing system. The terms no longer have any 
bearing on whether the device served by 
a particular driver happens to be built into 
a Windows CE product, or is added later 
by an end user. If a device driver uses a 
custom interface that is native to that type 
of driver, then the driver is called a “na- 
tive driver.” Conversely, if a device driver 
uses the stream-interface functions 
(FileOpen, IOControl) it is called a 
“stream-interface driver.” 

As the lead writer for Windows CE de- 
vice driver documentation, I bear much 
of the responsibility for not identifying this 
issue and resolving it earlier. I am very in- 
terested in continuing to improve our doc- 
umentation and am very interested in any 
input readers may have. I am writing this 
letter, however, in an attempt to forestall 
any additional confusion that may be 
caused by the explanation in James’s ar- 
ticle. 1am concerned that developers who 
read James’s article prior to obtaining the 
Windows CE Embedded Toolkit or Visu- 
al C++ products may expect to see the old 
device driver terminology, which no longer 
matches what is present in the product 
documentation itself. 

Jason Black 

jasonbl@microsoft.com 


Real Real-Time 

Dear DDJ, 

Your October 1998 issue on real-time 
computing brought back many memo- 
ries of things learned, some the hard 
way. I’ve been writing software for 35 
years, with some of it being event-driven, 
real-time applications. My most recent 
system is an environmental sound mon- 
itoring system with multiple test points 
spread over several miles. The Windows- 
based PC controller communicates with 
the instruments via spread spectrum RF 
modems. It also uses a Davis Instruments 
system similar to the one Richard Smith 
mentioned in his article “A Real-Time 
Weather Station.” 

The definition of “real time” needs 
careful examination. Robert Krten’s def- 
inition in the opening paragraph of his 
article “Device Drivers & Real-Time Sys- 
tems” (which I enjoyed very much, by 
the way) gives a reasonably good flavor 
but is lacking some important ingredi- 
ents. Rather than just responding to 
“events in a deterministic (and, hope- 
fully, fast) manner” the designer has to 
determine if the Joss of data is impor- 
tant. The system can be both determin- 
istic and fast and still lose information. 
Is this important? It depends on the ap- 
plication. 


Real-time instruments (that is, FFT 
spectrum analyzers) seem to fall into 
two categories. Manufacturers will call 
their instruments “real-time” but that can 
have two very different meanings. The 
better, in my opinion, means no loss of 
data. That is, they can process a buffer 
to calculate and display its FFT as fast 
or faster than the system samples its next 
buffer. However, some manufacturers 
call their system “real time” because the 
system gives the visual appearance to 
the operator of always displaying results. 
The system might be dropping out 20 
percent of the data, but if the display 
keeps updating with no noticeable blank 
periods, then it’s real time by their def- 
inition. If your bank didn’t credit you 
with 20 percent of your deposits but 
handled everything “in a deterministic 
(and, hopefully, fast) manner,” would 
you be happy? 

To me a system is real time if it can 
respond to events (time is just one type 
of event; so is a switch changing state) 
and do what needs to be done without 
having to resort to some kind of special 
processing to deal with more events than 
it can handle. Obviously, if you throw 
events at a system fast enough, it will 
reach the point where it can’t fully process 

(continued on page 16) 
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IMAGE FILE FORMATS 
(One of 16 technology categories) 
JPEG CMP 

-Lossy BMP 
-Lossless OS/2 BMP 
DICOM AWD 
FPX WMF 
EXF EMF 
PSD WPG 
PCD AVI 
EPS MSP 
1IOCA TIFF 6.0 
MODCA -Multipage 
CAL -JPEG 
ICO -Packbits 
CUR -Huffman 
PCX -RLE 
DCX -LZW 
IMG -CCITT 
DIB -CCITT G31D 
RAW FAX -CCITT G32D 
WFX -CCITT G4 
MAC -RGB 
VDA -Palletized 
GIF* -Grayscale 
PNG -Bitonal 
TGA -CMYK 
RAS -¥YCbCr 
PCT -CIELAB 


LEADTOOLS Supplies you with the Power to Integrate 16 areas of Imaging Technology 


IMAGE PROCESSING 
TRANSFORMS 


Including resize, resample 
(interpolated resize), rotate 
(.01 degree), flip, invert, 
reverse, crop, underlay, 
shear, transpose, stretch 
intensity, fill, auto deskew 
and combine (with mathe- 
matical and Boolean opera- 
tions). 


FILTERS 


Including sharpen, blur, 
average, edge detect, line 
detect, emboss, mosaic, 
posterize, median and noise 
filters, spatial filter (which can 
be pre-defined such as 
gradient, laplacian, sobel, 
prewitt, shift and difference, 
line segment, or they can be 
customized), and more. 


DRAWING 


Draw directly to a bitmap 
using windows GDI (such as 
TextOut, BitBit, Ellipse, and 
Rectangle), or use the 
ActiveX built-in drawing 
methods. 


REGION OF INTEREST 


Process only a_ specific 
portion of an image rather 
than the entire bitmap. 
Regions can be comprised of 
any combination of rectan- 
gles, ellipses, rounded- 
rectangles, freehand shapes, 
polygons, transparent color 
and more. 


LEADTOOLS is available in several versions, not all features are available in all versions. 


LEADTOOLS is the driving engine of choice. 


The leaders in software development choose award-winning 
LEADTOOLS imaging technology - companies like Microsoft, Hewlett 
Packard, Intel, Boeing, Xerox and thousands of others use 
LEADTOOLS in their high volume applications and internal systems. 
Why? LEADTOOLS gives developers the most flexible and powerful, 
imaging technology available. LEADTOOLS offers 16 areas of imaging 
technology, and makes it easy to add still frame, multimedia, document 
and medical imaging into applications by offering the choice of three 
application programmer interfaces: A low level API, a C++ class library 
and easy to use ActiveX controls. The API allows you to make low level 
DLL calls. With LEADTOOL's new C++ class library you get the control 
of low-level access and the ease of object oriented programming. Need 
development speed? With ActiveX controls you can develop at break 
neck speed using RAD components. All LEADTOOLS toolkits allow 
you to cut and paste from hundreds of ready-made source code 
You won't find another toolkit on the market containing 


examples. 


more imaging technology or easier to use than LEADTOOLS. .. 


SCANNING 


ISIS®, and TWAIN with 16 and 32 bit native 
mode and buffered RAM transfer modes. 


COLOR CONVERSION 


Depth conversion - 1 to 32 bit with 8 dithering 
methods. Color space conversion/separation - 
RGB, YUV, CMYK, CMY, YIQ, HSV & HLS. 
Grayscaling, brighten, darken, invert, hue and 
saturation, contrast, gamma correction, and 
histogram equalize. 


DISPLAY/SPECIALEFFECTS 


LEADTOOLS provides optimized rendering of 
any image to all display devices with monitor 
calibrations, auto-dithering, stretching, panning, 
zooming, scrolling, and animation. Choose from 
2018 paint effects, 36 gradients, 80 shapes, 12 
3D text styles, 64 dissolves and 43 transition 
effects, with delays, grain sizes, pattern brushes 
and acolored wand. 


ANNOTATIONS 


For documents or color images more than 17 
different objects, all with security passwords and 
hyperlinks. 


COMPRESSION 


Industry standard methods such as JPEG, PNG, 
Exif and CCITT G3/G4 as well as industry 
leading proprietary LEAD CMP. 


IMAGING COMMON DIALOG 


LEAD's unique common dialog customized for 
imaging, saves time and provides a consistent 
and professional interface. 


INTERNET/INTRANET 


LEADTOOLS features Net Aware ActiveX with 
ASP support and a Netscape plug-in. Load 
images from any URL. Support for Progressive 
JPEG / CMP, and special GIF* flavors (interlace, 
transparency, animation, and text). 


DATABASE 


LEADTOOLS has specific features designed for 
the imaging database developer: VB data 
binding, 32-bit ODBC, OLE DB, a customized 
OLE 2.0 in-place server, Load/Save memory, 
and Load/Save file offset. 


OCR 


Uses Xerox® TextBridge® recognition 
technology. Fonts recognized within the same 
image, callback functions for user input while 
processing, training OCR engine for improved 
recognition and multi-language support. 


SCREEN CAPTURE 


Capture entire screen, active window, selected 
menu, menu under cursor, selected window 
object (button, tool bar, icon, or client area), 
selected area (rectangle, rounded rectangle, 
ellipse, polygon or freehand) and resources 
stored in EXEs or DLLs. Options include multi- 
capture with callback, Hot Keys, and time 
interval. 


PRINTING 


LEADTOOLS performs all image processing 
necessary to print directly to any Windows 
supported printer, with the ability to print text and 
multiple images on the same page. 


MULTIMEDIA 


VIDEO: Play/edit multimedia objects. 
Play/Stop/Pause, set balance, volume, play rate 
and time format. Edit existing multimedia 
objects, or create new ones. Copy, delete, 
insert, paste, replace frames. AVI, MPEG1, 
MIDI, WAV and more are supported. CAPTURE: 
Audio/ video. Streaming with frame rate, single 
frame, audio, (volume, level, formats, and 
muting) and device selection. INTERNET: 
Create video, audio and data client server 
applications including video conferencing over 
the Internet/intranet. 


*License required from Unisys for formats using LZW compression. LEAD and LEADTOOLS are registered trademarks of LEAD 


Technologies, Inc. TextBridge® is a registered trademark of the Xerox Corporation. ISIS® is a registered trademark of Pixel Translations, a division of Input Software, Inc. All other product names are trademarks of their respective owners. 
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Server) 
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"LEADTOOLS is an indispensable tool, we 
used it in the development of our 


FrontPage™ application." 
Tom Button 
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(continued from page 12) 

everything. At this point, the system stops 
being real time. This does not mean the 
system itself should quit, just that it has 
to resort to some method, typically based 
on priorities, for dealing with the issue. 
For example, if a real-time process con- 
trol has to deal with monitoring reactor 
pressure, updating a display, and han- 
dling other events, it would, I’d hope, 
continue to monitor the reactor over 
updating the graphics display when oth- 
er events make it busy! 

Because our major software product 
can interact with other computer sys- 
tems, we occasionally get requests that 
the information in the Windows appli- 
cation be updated in real time. That 
prompts us to ask what they mean by 
“real time.” What this usually means is 
they want the data to quickly get into 
the application from the other system. If 
a few seconds is “quickly,” then it can 
be done. 

Windows, of course, is not a real-time 
operating system, and woe to any pro- 
grammer who thinks otherwise. Even its 
multitasking capabilities are basic; it relies 
on cooperation between programs. If 
you're not careful, you can easily write an 
application that hogs the CPU and pre- 
vents other apps from running. 


If you're careful, keep everything in one 
application, and don’t run other Windows 
programs at will, VB can do a fairly de- 
cent job of handling various tasks on an 
event basis. The environmental monitor- 
ing program mentioned earlier is a VB 
app. We do sampling from multiple in- 
struments and the weather system, write 
data to disk, update a display map, print 
reports, and plot past data in “real time.” 
Each midnight, the system also creates the 
new day’s disk files and closes out yes- 
terday’s without loosing a beat. 

Beware of the time event, however. It 
doesn’t work as you might guess. You 
can set up a timer event for, say, one 
second, but it doesn’t work that way. 
Robert Krten discussed latency and oth- 
er aspects of time, so I won’t repeat 
them. However, do be careful when us- 
ing the VB clock, because while you can 
read the time to something like a mil- 
lisecond, it really only “ticks” in some- 
thing like 55 ms increments (I’m writing 
this from memory, so I may misquote a 
bit). In any case, you can’t get a nice, 
even One-second interrupt! 

We wanted one-second sampling, so 
we added a National Instruments board 
and tied a one-second time driven by 
line frequency from the board to a spare 
hardware interrupt. The board and com- 


panion software makes it easy to do. The 
result was an extremely reliable one-sec- 
ond sampling interval. I was intrigued 
by Robert Krten’s idea about using the 
serial port to generate a timer event. I 
need to think about that for a while. It 
seems to me that it may need constant 
“feeding” to keep up the data stream that 
generates the clocking. I wonder if it’ll 
maintain its interval over long time. But 
the price is certainly right. 

The one piece of advice someone 
should get from all this is that when the 
term “real time” is used, be sure there’s 
agreement on the definition, or you may 
not get what you expect. 

Norman R. Dotti, president 

Knorr Associates 

mailroom@knorr.com 


Errata 

In Figure 2 of “Smart Cards and the Open 
Terminal Architecture,” by Edward K. Con- 
klin (DDJ, December 1998), the upper-right 
box should read “Nonvolatile Extended 
Memory (Module Repository).” The lower- 
right box should read “Nonvolatile Ex- 
tended Memory (Databases).” We apolo- 
gize for any confusion. 


DDJ 
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Java and Lightweight 





Components 





Implementing platform- 
independent look-and-feel 





David K. Perelman-Hall 


y now you know that you can write Java code once, then run 
it in any virtual machine— no matter what platform is hosting 
the VM. However, if you write code that uses UI components 
native to the platform hosting the VM (which is what the Ab- 
stract Windowing Toolkit (AWT) does for each UI widget in 
the toolkit), the write-once/run-anywhere quality of Java has 
to have a door to the native implementation. That makes Java 
code using the AWT dependent on platform-specific resources. 

If you've paid attention to how Java AWT components look 
on different platforms, you know that UI components look like 
those of the platform proper. Java achieves this by forwarding 
requests for the creation of AWT UI components to platform- 
dependent UI peers, which render their on-screen representa- 
tions using native platform-dependent UI resources. This means 
that with the AWT there is no single cross-platform implemen- 
tation of any UI component. It also means that every VM that can 
display AWT components has access to a platform-specific set of 
peer classes to render the AWT components. 

Forwarding to peers is dubbed the “heavyweight component” 
technique because peers make heavy use of resources— each 
heavyweight component renders itself using a separate native 
window with its own native graphics resources. Native windows 
also impose certain, perhaps unwanted but immutable, charac- 
teristics, including a square shape and opacity, which are in- 
herited when you subclass the AWT, thus making it difficult to 
build a set of, say, round or partially transparent components. 

In contrast to the heavyweights, JDK 1.1 lightweight com- 
ponents let you give programs the same look for components, 
no matter which platform hosts the VM, because lightweights 
don’t use peers. Instead, lightweights get rendered by pro- 
grammer-defined code, and can have any shape— even trans- 
parent sections. They use fewer resources than their heavy- 
weight siblings because, instead of using a native window for 
every component, lightweights render themselves using the na- 


David develops client/server Java software at NetGenics Inc. in 


Cleveland, Ohio, and teaches Java for Sun Microsystems. He can 
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tive window graphics resource of their nearest heavyweight 
ancestor. An example of a full-fledged lightweight library is 
Sun’s SwingSet, delivered with the JDK 1.1. 

To examine lightweight component development, I present 
my dph.awt.lightweight package and an alarm-clock applica- 
tion made of lightweight pieces, which runs in a Java Frame 
and can be used as an application or applet. The code for this 
application (available electronically; see “Resource Center,” 
page 5) requires JDK 1.1 and will not compile under JDK 1.02. 
When run as an applet, the alarm clock works under Netscape 
Navigator 4.04, but requires the latest JDK 1.1 patch. 


The Overall Picture 

The dph.awt.lightweight package I present here demonstrates 
the steps of lightweight component development. It is not a 
complete lightweight component set. Nor am I providing ex- 
act replacements for AWT components (the AWT doesn’t even 
have a Spinner class). Instead, I’m providing components that 
overlap with the AWT. My FlatButton and Label, for example, 
could be replacements for AWT Button and Label, but my La- 
bel lets you designate a border, and my FlatButton does not 
look or behave like an AWT Button. 

There are five components that make up the dph.awt. lightweight 
package: Label, Checkbox, Spinner, FlatButton, and TabPanel. There 
is also a RoundButton class, but it is not used in the alarm clock. 
Except for TabPanel, these inherit from class dph.awt.lightweight.Com- 
monBase, which principally encapsulates a behavioral pattern used 
to size lightweight components. CommonBase inherits from 
java.awt.component, while TabPanel inherits from java.awt.Con- 
tainer. These are the only JDK parents lightweights can have. Fig- 
ure 1 provides an overall view of the classes making up the 
dph.awt.lightweight package. 

Additional classes include dph.play.alarmclock.AlarmClockFrame 
(the window in which the alarm clock appears), dph.play.alarm- 
clock.AlarmClockApplet (the applet that invokes AlarmClockFrame to 
let the alarm clock run as an applet), dph.play.alarmclock.Clock- 
Canvas (the clock face), and dph.play.alarmclock.SecondsThread 
(a subclass of java.lang.Thread that does the timing of the clock). 
There are also nested inner classes for event handlers. 

There are three canonical steps of lightweight development. 
Lightweights are required to: 


e Inherit from java.awt.Component or java.awt.Container or 
another lightweight. 

e Do all the drawing required to represent the component on 
screen, including any graphical behavior that would nor- 
mally occur in reaction to mouse events. 
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¢ Do the event handling appropriate to the component. This means 
you must provide the hooks to let listeners register and deregis- 
ter for notification that an event has taken place, and you must 
pass the event notification to the listeners. 


In addition, if the lightweight component you are creating is 
a container (like TabPanel) and not just a component, then it 
is essential that you call superpaint, because containers are re- 
sponsible for drawing the components they hold, and calling su- 
perpaint ensures that this responsibility will be fulfilled. 


The First Canonical Step 

The first step is that all lightweights extend java.awt.Component, 
java.awt.Container, or another lightweight. For the alarm clock, the 
class CommonBase performs this step for the noncontainer 
lightweights, such as Label, Spinner, FlatButton, and Checkbox. The 
lightweight container TabPanel extends directly from java.awt.Con- 
tainer. Listing One is the skeleton class definition for CommonBase. 

Sizing, painting, and enabling/disabling behaviors are partly man- 
aged in this base class. Many sizing activities rely on a font to de- 
termine how large to draw a component, and, in Java, a font is 
part of the graphics context for a component. Thus, it is often im- 
portant to delay size calculating until a graphics context has been 
established. The call to addNotify ensures a graphics context is 
available, so CommonBase overrides this to call figureMySize once 
the graphics context has been supplied. Each child class only needs 
to define the hook method figureMySize to return the Dimension 
object, which represents the preferred size of the object. 

The second behavior managed by this class is painting. 
Lightweights tend to have noticeable flicker that can be re- 
solved by the use of off-screen image buffering, sometimes 
called “double-buffering.” Double-buffering prepares the screen’s 
contents initially in an image buffer in memory, and then with 
the paint method whisks the image in memory onto the screen. 

The solution involves placing lightweights in containers which 
do the buffering, then overriding update in the components’ call 
to paint, thus omitting the default behavior of clearing the screen 
in update. CommonBase implements the override of update so 
none of its child components need to. The double-buffering in the 
container classes DoubleBufferedPanel and DoubleBuffered- 
ExitingFrame is based on examples in the demo/awt- 
1.1/lightweight directory of the JDK1.1. 

The third behavior is enabling/disabling, which is overridden 
merely to enforce a repaint occurring as a result of a change to an 
enabled state. 


The Second Canonical Step 

The second step is to provide constructors and methods for ma- 
nipulating the state of the component, including its appearance. If 
you are creating a component to replace one of the AWT com- 
ponents, extending java.awt.Component gives you the methods 
and data of the Component class, so look at the methods of the 
AWT class you are replacing, and supply the constructors, data 
members, and method implementations needed to make your 
lightweight component behave like the AWT component. Most Java 
reference books itemize the data members and class methods for 
the AWT components, but I recommend Java AWT Reference, by 
John Zukowski (O’Reilly & Associates, 1997). 

I provide at least a minimum set of constructors for lightweight _ 
components; see Label in Listing Two. I define a set of construc- 
tors that creates a Label with a textual String. | also let users des- 
ignate whether there should be a rectangular border around the 
Label. Label’s flaw is that it will always draw its text left justified. 
This means that if users call setSize to give a Label a wide 
graphical representation, the text won’t appear in the middle 
of that area. 


Dr. Dobb’s Journal, February 1999 


a 


. 


we 


pret 


po ets hh 


as 


By PE 


el | 


tig 





. 
¥ 


z 
: 





Mhnson Studios: 





SBR TE METRO EL ENOTES O TE ETS EEA OTS ED TE TE TE RI TIT ET EIEN I TTI EE TI ESD II EI PET NSB PN NSS TT PS IR TR PP ER I PH NT NN TN EPC EEN RE VRE RS I ED SHS ESS NER EH RR RESP SRE 


One of the more interesting classes is FlatButton, which lies 
flat and pops up when the cursor moves over it. FlatButton dif- 
fers from the AWT Button in that it lets you have a textual la- 
bel, an image label, or both, on the surface of the button. If 
both are there, FlatButton draws the text over the image. To get 
it to appear with an image, pass the constructor a String repre- 
senting the URL of the image you want painted on its surface. 
You can also call setimageURL after it has been constructed, and 
pass in the String representing the URL. One of the tricks this 
class employs is the use of a MediaTracker object to ensure that 
the image is loaded. It is essential to have a valid image before 
trying to use the image to determine the FlatButton’s dimen- 
sions. Listing Three shows the steps FlatButton takes to ensure 
that the image is fully loaded before figuring its size. 

You must control all aspects of a lightweight’s appearance, 
and FlatButtons appear to pop up when the cursor enters them, 
pop down when pressed, or go flat when the cursor exits them. 
Consequently, the class must track these states, and the drawing 
code in the paint method must shift the image and/or text when 
it changes state. You must even handle the differences in ap- 
pearance and behavior between the enabled and the disabled 
states for each lightweight component. 

In fact, because you must control every aspect of the 
lightweight component’s appearance, you must override the 
paint method to draw the component. Bear in mind that the 
double-buffering (to control flickering) does not take place in 
the components themselves, but rather should take place in the 
container the components are placed in. Therefore, you won't 
see any evidence of double-buffering in the paint methods of 
these lightweights. In fact, they are not aware of being double- 
buffered. If done correctly, however, the Graphics object that is 
used in their paint methods will originate from the buffered Jm- 
age of the highest-level container they are in. 

The only lightweight under discussion, which extends 
java.awt.Container and not java.awt.Component is TabPanel. 
To ensure that this class behaves more like a tabbed folder than 
a Panel, the TabPanel class does not implement a host of meth- 
ods inherited from java.awt.Container, such as ddd, getCom- 
ponent, getComponentCount, remove, and removeAll. The class 
data supporting the 7abPanel are minimal: 


e An array of String to hold the tab labels. 

e An array of Rectangle designating regions of the screen where 
the tabs are drawn so that mouse clicks can be associated 
with particular tabs. 

e An int to designate the currently selected tab. 








Figure ye Classes that make up the dph.auwt. lightweight 
package. 
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e A Hashtable to hold the contents of each tab in the form of 
Panels keyed to their tab labels. 
e A DoubleBufferedPanel called currentPanel. 


To use TabPanel, users build up a Panel outside of TabPanel by 
adding components to a Panel, then invoking one of the TabPan- 
el add methods to add the Panel to the TabPanel along with a la- 
bel that appears in a tab for that Panel. This TabPanel has two flaws: 


e Tabs are only positioned across the top of the folder. In fact, 
there is a trick to how tabs appear as a separate row of features 
above the folder for each tab. Because the TabPanel itself is a 
Container, it has a LayoutManager which controls how the com- 
ponents on it are laid out. The TabPanel nulls out its Layout- 
Manager, and each Panel selected by a mouseclick on a tab is 
positioned by the call currentPanel.setLocation(2,27). Thus, there 
is a row 27 pixels tall above each Panel, this is where the tabs 
are drawn. 

e The row of tabs across the top of the TabPanel will not in- 
telligently handle more tabs than there is horizontal space for 
as determined by the width of the 7abPanel. 


The real work of this component is done in the methods called 
from the paint method, which is split into three chores (see List- 
ing Four), the first of which is the all-important task of any 
lightweight container, calling superpaint. The second task is to 
draw the 7abPanel so that it has a background color and bor- 
der; the third task is to paint the tabs, showing which one is 
currently selected. It is possible to have the TabPanel show first 
without any tab being selected. The code in the set-SelectedTab 
method (Listing Five) shows how the panels are swapped when 
users click on different tabs. 


The Third Canonical Step 

Except for TabPanel (which calls it directly by itself), all con- 
structors eventually call enableEvents‘(AWTEvent. MOUSE 
_EVENT_MASK) through their common parent lightweight com- 
ponent CommonBase. The final canonical step, therefore, is to 
provide the means to let event listeners register with lightweights 
and receive notifications of the types of events appropriate to 
the component. This is a multipart process that involves: 


e Enabling lightweight components to receive event notifications 
appropriate for them (this is what’s going on in the call to en- 
ableEvents). 

e Giving event listeners a way to register with a lightweight com- 
ponent so that the listeners can be notified when the lightweight 
component has an event of interest. 

e Having the lightweight component disperse the event to regis- 
tered listeners. 


Pll show how this is done using the FlatButton, Checkbox, 
and Spinner lightweight classes. 

The java.awt.Component method enableEvents(int eventMask) 
allows a component to listen for those events designated by the 
eventMask parameter (defined in the AWTEvent class to have val- 
ues such as WINDOW_EVENT_MASK and MOUSE_EVENT_MASK), 
and to do so without having any registered listeners. In Java 1.1, 
events are not normally produced when there are no registered lis- 
teners, but this technique ensures that events are generated. You 
can turn off listening by calling disableEvents(int eventMask). 

Because each of my lightweight UI components is the target 
of some mouse activity in the constructor class CommonBase, I 
enable each lightweight to receive mouse events by calling en- 
ableEvenis with the argument set to MOUSE_EVENT_MASK. Each 
of the child classes uses the event notifications differently. For ex- 
ample, a FlatButton can pop up in reaction to a mouse-entered 
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(continued from page 24) 

event, Spinner can start a thread that changes its value in re- 
sponse to a mouse-pressed event, and it can stop the thread 
when it gets a mouse-released event; and Checkbox can change 
its state in reaction to a mouse-clicked event. 

With every instance of an event source (like a button object), 
there is a list of listeners that have registered interest in being no- 
tified that an event has taken place. All you need to know is what 
type of event is being listened for, then keep a reference to the list 
of listeners in your own class. The way to access this list is through 
the AWTEventMulticaster class, which lets you have access to this 
listener chain so that you can insert or remove listeners, and, so 
that you can then deliver your own event to the chain. 

Buttons normally let listeners register to listen for ActionEvent, 
so you define the addActionListener and removeActionListener 
methods (like standard AWT Buttons have), and use the static add 
and remove methods of the AWT7EventMulticaster class to add or 
remove an ActionListener to instances of your buttons; see Listing 
Six. The adding/removing of listeners is done at the ButtonBase 
class level and is inherited by both FlatButton and RoundButton. 
In Listing Six, the reference being assigned the return from 
AWTEventMulticaster.add or remove is actionListener, which 
is a protected data member in the ButtonBase class. The 
dph.awt.lightweight.Spinner class also registers ActionListeners. 
Checkboxes register JtemListeners that want notification when the 
state of the checkbox changes, so you keep a reference to Jtem- 
Listener and use the AWTEventMulticaster class to reference the 
checkbox’s list of listeners. 

Finally, you need to process events appropriate to the compo- 
nent. Because every button type should respond to a mouse-click 
by generating an ActionEvent for its listeners, I've put that behav- 
ior in the ButtonBase class. Listing Seven tests if the button is en- 
abled by using the java.awt.Components isEnabled method, then 
tests if it has any registered listeners, and then calls actionPerformed 
on the list of listeners. The parameters to actionPerformed are: a 
reference to the source of the event (which you provide by a ref- 
erence to this), an event ID, and the command string. Placing this 
responsibility in the parent class necessitates a call to superpro- 
cessEvent in the FlatButton and RoundButton child classes. 

As Listing Eight shows, you respond to mouse activity in Flat- 
Button by manipulating state information, which you use to 
draw the current state of the button. The call to super process- 
Event is outside of the tests and takes place every time. 

Finally, dpb.awt.lightweight.Spinner handles mouse activity by 
tracking whether users press on the spinner’s up- or down-arrow, 
then calls spin, which starts a thread to increment or decrement 
the spinner’s value. It uses a thread because users might leave the 
mouse button pressed down while on the spinner arrow, and the 
expected behavior would be to continue changing the spinner’s 
value while the button is pressed. Because it wants to start a thread 
in reaction to every mouse-down on a spinner arrow, and because 
users might repeatedly click on it in rapid succession, there is a 
built-in time delay, which prevents threads from being built willy- 
nilly and causing the control to spin too rapidly. 

The spin method (Listing Nine) shows a reasonable use of a lo- 
cally defined class, which is a class nested not only within anoth- 
er class, but within a method as well. Usually this is a maintenance 
headache, but here, the sole purpose of the thread is to spin the 
value up or down, and the class is short and can be understood 
fairly quickly. It makes sense to keep it together with the function 
that uses it. You can see that the spin function does only two things — 
it defines the SpinThread class and calls start on an instance of it. 
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Listing One 


package dph.awt. lightweight; 
public abstract class CommonBase extends java.awt.Component { 
public void addNotify() { 
super.addNotify () ; 
java.awt.Dimension d = getSize(); 
if( d.width == i, @.height == @ ) { 
setSize( this.figureMySize( this.getGraphics() ) ); 
} 
} 
public void setEnabled( boolean state ) { 
super.setEnabled( state ); 


repaint (); 

} 

public void update( java.awt.Graphics g ) { 
paint( g ); 

} 


public java.awt.Dimension getMinimumSize() { 
return getPreferredSize() ; 
} 
public java.awt.Dimension getPreferredSize() { 
if( getSize().width != @ && getSize().height != 0 ) 
return getSize(); 
else 
return figureMySize( getGraphics() ); 
} 


protected abstract java.awt.Dimension figureMySize( java.awt.Graphics g ); 


Listing Two 


public Label() { 
this( "", false ); 
} 
public Label( String text ) { 
this( text, false ); 
} 
public Label( String text, boolean showBorder ) { 
super (); 
this.text = text; 
this.showBorder = showBorder; 


Listing Three 


public FlatButton ( java.awt.Image image ) { 
super( "" ); 
this.image = image; 
this.setup(); 
} 
private final void setup() { 
if( image != null && (image.getWidth(this)==-1 {| 
image. getHeight(this)==-1) ) 
this.ensureImageLoaded( image ); 
} 
private final void ensureImageLoaded( java.awt.Image image ) { 
try { 
java.awt.MediaTracker tracker = new java.awt.MediaTracker( this ); 
tracker.addImage( image, 2 ); 
tracker.waitForID( @ ); 
Util.assert( tracker.statusID(@, false) == 
java.awt.MediaTracker.COMPLETE, "image complete" ); 
} catch( InterruptedException ex ) { 
Util.debug( "Image loading interrupted" ); 
} 


Listing Four 


public void paint( Graphics g ) { 
super.paint( g ); 
this.paintTabPanel( g ); 
this.paintTabs( g ); 


e e ° 
Listing Five 
public void setSelectedTab( int tabNum ) { 
if( tabNum >= @ && tabNum < tabLabels.length ) { 
this.remove( currentPanel ); 
selectedTab = tabNum; 
currentPanel = (DoubleBufferedPanel)cards.get( tabLabels[tabNum] ); 
this.add( currentPanel ); 
currentPanel.setLocation( 2, 27 ); 
currentPanel.setSize( this.getPanelSize() ); 
} 


repaint (); 


° ° e 
Listing Six 
wt 
public void addActionListener( ActionListener al ) ( 
‘ -innListener = AWTEventMulticaster.add( actionListener, al ); 
} ay 3 
public void removeActionListener( ActionListener al ) { 
actionListener = AWTEventMulticaster.remove( actionListener, al ); 


} om 
RY 
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8 t i if( isEnabled() ) { 
es ers” if( actionListener != null ) { 


{/) Listing Seven 
eve 'e) of) rs _—— bed / public void processMouseEvent( MouseEvent me ) { 
, switch( me.getID() ) { 
case MouseEvent .MOUSE_CLICKED: 
actionListener.actionPerformed( new ActionEvent ( 
n sync |! this, ActionEvent.ACTION_PERFORMED, this.getActionCommand () 
ie 


| } 
Coordinate } 


super.processMouseEvent( me ); 
your Team Efforts } 
for Top Quali 
_ Software bevelpment Listing Eight 


public void processMouseEvent( java.awt.event.MouseEvent evt ) { 
if( isEnabled() ) { 

switch( evt.getID() ) { 

case java.awt.event .MouseEvent .MOUSE_ENTERED: 
mouseIsIn = true; 
repaint () ; 
break; 

case java.awt.event.MouseEvent .MOUSE_EXITED: 
mouseIsIn = false; 
repaint () ; 
break; 

case java.awt.event .MouseEvent .MOUSE_PRESSED: 
mouseIsDown = true; 
repaint () ; 
break; 

case java.awt.event.MouseEvent .MOUSE_ RELEASED: 
mouseIsDown = false; 
repaint () ; 
break; 


e e e 
Listing Nine 
public void spin() { 
class SpinThread extends Thread { 
SpinThread() { 


super (); 
this.setPriority( Thread.MIN_ PRIORITY ); 


public void run() { 


try { 
if( upPressed ) 
increment () ; 
if( dnPressed ) 
decrement () ; 
repaint (); 
Thread.sleep( 1250 ); 
while( upPressed |; dnPressed ) ( 
if( upPressed ) 
increment () ; 
if( dnPressed ) 
decrement () ; 
repaint (); 
Thread.sleep( 400 ); 
} 


} catch( InterruptedException ex ) { 
// ignore it 
} 


} 
new SpinThread().start() ; 


DDJ 
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A Java Applet 


Search Engine 





Full-text searching is 
not Just for web sites 





Tim Kientzle 


TML is perfect for CD-ROM pub- 
lishing: Tools for authoring and 
managing HTML are mature and 
stable, and most users already have 
a browser (and if they don’t, you can 
usually include one on your CD for 
free). One weak point, on the other 
hand, is searching. If you have 200 MB 
of HTML, you’d like to provide users 
with a way to rapidly find information. 
However, most search engines are de- 
signed for use on web sites, and have 
to be started by a web server in re- 
sponse to certain requests. 
The search engine I present here uses 
a Java applet to handle searches. This 
works well on CD-ROMs, although not 
without complications (see the accom- 
panying text box, entitled “Java Applets 
on CD-ROM”). The applet uses an in- 
dex database built by a Perl indexing 


Tim is senior technical editor for DDJ. He 
can be reached at kientzle@ddj.com. 
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program I described in “Full-Text 
Searching in Perl” (DDJ, January 1999). 

My full-text search applet works like 
this: To find all HTML files that contain 
“java search engine,” you first look up 
each separate word in a_ prebuilt 
database. Thus, when you look up “java,” 
you might get the list 27, 28, 29, 38, 43, 








. od aoe rs 


79, 88. Looking up “search” and “engine” 
will give similar lists. You can easily com- 
bine these lists to find the files that match 
any particular Boolean expression. You 
then look up each file number to obtain 
a file description and display that infor- 
mation to users. 





The Database 

The first requirement for my applet was 
that it be able to access the on-disc 
database. Since I used Perl to create the 
database, I needed a database format that 
could be accessed from both Perl and 
Java. Berkeley DB (http://www.sleepycat. 
com/) is a portable C library with a clean 
interface to Perl. Although Berkeley DB 
does have a Java API, it works by call- 
ing the C library, an approach I could 
not use. Consequently, I wrote my own 
Java classes to read Berkeley DB 
B-Tree files. 

A Berkeley DB file consists of a series 
of pages, all the same size. Page 0 con- 
tains the metadata in Table 1. The magic 
number is used not only to identify the file 
type, but also to determine the endianess 
of the platform that created the file. By 
recording the order of the 4 bytes 0x00, 
0x05, 0x31, and 0x62 at the beginning of 
the file, you have a template for decoding 
4-byte integers throughout the file. 

Except for Page 0, all pages have a 
layout like Figure 1. The fixed-size head- 
er (Table 2) indicates certain basic facts 
about this page. The pointers are 4-byte 
offsets to nodes. As the page is filled, 
the pointers grow up and the nodes 
grow down into the free space. 

In Table 3, a node on an internal page 
contains a key and the number of the 

(continued on page 30) 
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Table 1: Metadata (Page O) for a Berkeley DB. 
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page containing elements greater than 
or equal to that key but smaller than the 
next key. For leaf pages, each node has 
a key and a data item. 

If a key is too big to fit in a page, the 
overflow-key bit is set in the flags, and 
the key is replaced by the page number 
where the actual key is stored. If the key 
spans more than one overflow page, the 
“next page” field can be used to chain 
together multiple overflow pages. Very 
long data items are handled similarly. 


The DBBTree Classes 

My Java code that reads Berkeley DB files 
consists of three classes. The primary 
class (and currently the only public class) 
is DBBTree (Listing One). You create a 
DBBTree object by giving it a filename 
or File object. It opens the file, reads the 
metadata, and then provides access to 
the database through the search() 
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method, which accepts a byte array with 
the desired key, and returns another byte 
array with the corresponding data. 

DBBTree handles the file management. 
It uses a RandomAccessFile() object to 
access the data and manages a cache of 
pages. The searching is handled by two 
auxiliary classes. DBBTreePage takes a 
byte array containing a DB page and pro- 
vides a set of methods to access that 
page. This includes a search() method 
that searches that page for the indicated 
key. DBBTree handles searches by sim- 
ply reading Page 1, creating a DBB- 
TreePage object, then asking that object 
to search itself, | 

A DBBTreePage searches itself using a 
simple binary search. It uses the DBB- 
TreeNode class to access particular nodes 
and compare them to the requested key. 
If the DBBTreePage is an internal page, 
it identifies the correct child page, asks 
the DBBTree object to fetch that page, 
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then asks that page to search itself. This 
process continues recursively until a leaf 
page searches itself and either returns the 
desired data or returns a null value to in- 
dicate failure. 

Every page or node object has a refer- 
ence to the top-level DBBTree object. This 
allows any page or node to request a 
page. For example, if I need to add sup- 
port for overflow keys or data, nodes will 
then be able to directly request those 
pages. This way, I preserve the abstrac- 
tion that leaf nodes contain key/data pairs 
directly. 

My current DBBTree package does not 
support writing to the database, deleting 
items, database cursors, or duplicate keys. 
However, the file format does support 
them, and my package should be easily 
extendible if I ever find such features nec- 
essary. Eventually, I hope to flesh this 
out and package it as a JDK 1.2-style col- 
lection class. That would make it easy to 
write fairly generic Java code that oper- 
ated essentially the same regardless of 
whether the underlying storage was mem- 
ory or disk. 


Java and Files 

Java supports URLs very well, but is 
somewhat myopic about filenames. For 
my search applet, I need to open a file 
called “index.db.” But, it’s probably not 
in the current directory, so I need to 
somehow generate the full path name. 
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Figure 1: B-Tree page. 


(continued from page 36) 

Java does not provide a direct way to 
obtain the filename from which a docu- 
ment was loaded. Applet.getDocument- 
Base() will tell you the URL, but a URL is 
not a filename. Java does not provide a 
way to convert a “file:” URL into a local 
filename. 

My solution is the messy piece of code 
in Listing Two that uses Applet.getDoc- 
umentBase() and the java.net.URL class 
to build a “file:” URL for the index.db 
file. I then simply try several combina- 
tions of path separators and other 
changes to build a filename that will suc- 
cessfully open. 


Interactive Searching 

One advantage of running on CD-ROM 
rather than over a network connection 
is that you have direct access to the 
database. Figure 2 shows the search ap- 
plet interface. Note there are no buttons. 
I don’t ask you to type your request and 
press a button to see the results. Instead, 
I update the search results with every 
keypress. 

Full-text searching against a database 
is suited for this type of interactive search- 
ing. To rebuild the “Words” listbox in Fig- 
ure 2, for instance, I need to first parse 
the query string and then look up each 
word in the database. Because I’m re- 
— the search on every ie 





probably only one word has changed 
since the last search. The words that 
haven’t changed are stored in memory, so 
I only need to look up one word in the 
database. B-Trees store their data in sort- 
ed order, and the changed word has prob- 
ably changed at the end. So the changed 
word is probably on the same database 
page, and that page is probably still in the 
database cache. Hence, It’s quite likely 
that you can rebuild the “Words” listbox 
without going to the disk at all. 

However, the “Articles” listbox is more 
time-consuming to update. A particu- 
lar search may have completely differ- 
ent results than the previous search, so 
you can’t rely on caching to save you 
from several hundred database probes. 
Worse, most AWT implementations 
completely redraw the listbox on every 
change, even if that change is not vis- 
ible on the screen. This policy dramat- 
ically slows listbox updates; I’ve seen 
it take nearly 15 seconds to add 1000 
or so entries to a standard listbox, even 
on fairly fast machines. 


Lazy Listbox 

Of course, you don’t need all of the re- 
sults immediately. All you really need 
are the first 15 or so entries (so you can 
draw the listbox display) and the total 
number of entries (so you can size the 
vertical scroll bar appropuaiety). 
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My lazy listbox accepts an array of in- 
tegers and a database handle. It then 
proceeds to look up file numbers in the 
database only when they are needed for 
the display. The complete listbox im- 
plementation requires a Canvas (for the 
actual display), two scroll bars, and some 
layout glue to package it together. I de- 
liberately wrote for JDK 1.0 to support 
older browsers. 

My lazy listbox involves some inter- 
esting details. For example, since I don’t 
already know all of the strings, I don’t 
know how to best size the horizontal 
scroll bar. Instead, I simply track the 
maximum width of the strings I have 
seen and read just the horizontal scroll- 
bar as I find out more information. In 
practice, this means that as you scroll 
the listbox vertically, the horizontal 
scroll button will shrink. 

Things I learned about Java when im- 


my custom listbox, I drew it manually. 
e On different Java systems, the scroll- 
bars send different events. (On one 
platform, the scrollbars send a string 
of mouse-move events when you 
move the mouse over the scrollbar.) 


Java is somewhat 
myopic about 
filenames 


Le eee 


scrolling; you have to simply redraw 
the entire display. 


Fine Points 

Thanks to feedback from a number of 
people, I incorporated numerous details 
to improve my search applet and make it 
easier to use and configure. For example, 
every text string you see in the user in- 
terface is defined by a parameter. That 
way, you can simply change the HTML 
page to translate the interface into a new 
language. 

When you point to an article name, 
the corresponding URL is handed to 
Applet.showStatus(). This follows the 
common convention that reference tar- 
gets are displayed in the browser status 
line. My original applet used double-click 
to display an article; I changed this be- 
cause most web browsers use single- 
click to follow a reference. 


The full source is available electron- 
ically (see “Resource Center,” page 5). 
I’ve also included a sample index 
database generated from the last 10 
years of DDJ. This database was creat- 
ed from 2500 articles, comprising 64 MB 
of HTML. 





plementing this custom listbox include: 


e JDK 1.0 and JDK 1.1 handle the max- 
imum and minimum values for scroll 
bars differently. I haven’t seen this 
mentioned in any Java documentation. 

e java.awt.Graphics.draw3DRect() com- 
putes highlight colors using its own 
technique, which doesn’t match any 
particular platform, much less the cur- 
rent one. To get a nice border around 


It was important to explicitly check 
for the events I wanted to avoid need- 
less redraws. 

e Generally, Java AWT implementations 
do a lot of needless redraws; be care- 
ful not to compound this problem. 

e Java AWT doesn’t provide a blit func- 
tion, so there’s no way to accelerate 


DDJ 
(Listings begin on page 40.) 
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Listing One 


public class DBBTree { 


protected RandomAccessFile file; 
protected File fileName; 
private int pageSize; // page size 
private boolean msbFirst; // True = MSB byte order, False = LSB byte order 
/** The constructor takes a File name or File object. */ 
public DBBTree(String name) throws IOException { 
this (new File(name)) ; 


public DBBTree(java.io.File name) throws IOException { 
fileName = name; 
try { 
file = new RandomAccessFile(name,"r") ; 
} catch (SecurityException e) { 
throw new I0Exception("Wrong permissions for "tnamet": "te); 
} catch (IOException e) { 
throw new IOException("file open failed: " + e); 
} 
/* Read the metadata. I only read the first three values. */ 
pageSize = 256; // Big enough to get all of the metadata 
byte [] metaData = readRawPage(@); // Page @ holds metadata 
// Read magic number and determine endianness of DB file 
msbFirst = true; // Try MSB format first... 
int magic = bytesToInt(metaData,Q) ; 
if(magic != 0x053162) { // Failed? Try LSB... 
msbFirst = false; 
Magic = bytesToInt (metaData,Q) ; 
System.out.println("Opening LSB format database"); 
} else 
System.out.println("Opening MSB format database"); 
// Read version number and abort if not a DB file. 
int version = bytesToInt (metaData,4) ; 
if((magic != 0x053162) || (version != 3)) // BTREE Magic number & version 
throw new I0Exception("Not a DB file (magic: Ox" 
+ Integer.toHexString(magic) + ", version: " 
+ Integer.toString(version) + ")"); 
// Set actual page size 
pageSize = bytesToInt(metaData, 8); 
setCacheSize(8) ; // Set the cache to 8 pages as default 
primeCache(); // Pre-read first 8 pages into cache 

} 

/** Search for a key. A 'key' here is a byte array. Returns the data 
* associated with the key or null if the key wasn't found. */ 

public byte [] search(byte [] key) throws IOException { 

return readPage(1).search(key) ; // Search always begins on page 1 

} 

/** Read a raw page, return an array of bytes containing that page. */ 

protected byte [] readRawPage(int pageno) throws IOException { 

try{ 

byte data[] = new byte[pageSize] ; 

file.seek(pageno*pageSize) ; 

file.read(data) ; 

return data; 
} catch (IOException e) { 

throw new I0Exception("readRawPage("+pageno+") failed: " + e); 
} 

} 

/** The cache is kept in LRU (least-recently-used) order; that is, whenever 
* a page is accessed, it gets moved to the front of the list, and pages 
* are lost when they fall off the end of the list. Happily, this code is 
* simpler than the corresponding C version, thanks to the GC. */ 

int cachePageNumbers [] ; 

byte cachePages[] (]; 

/** Set the cache size. By default, it's set to 8 pages. */ 

public void setCacheSize(int size) { 

int[] newCachePageNumbers = new int[size]; 
if(cachePageNumbers != null) 

for(int i=0;i<size && i<cachePageNumbers. length; i++) 
newCachePageNumbers[i] = cachePageNumbers [i] ; 
else 

for(int i=0;i<size;it+) 
newCachePageNumbers [i] = @; 
cachePageNumbers = newCachePageNumbers; 
byte[] [] newCachePages = new byte[size] []; 
if(cachePages != null) 

for(int i=0;i<size && i<cachePages.length;it++) 
newCachePages[i] = cachePages [i]; 
cachePages = newCachePages; 

} 

/** Fill the cache with the first pages in the database. This can improve 
* perceived performance noticably. In particular, this pulls in page 1, 
* which is the top page of the B-Tree, and is searched on every lookup. */ 

public void primeCache() throws IOException { 

Ine tm (1 

while (cachePageNumbers [cachePageNumbers.length-1] == @) { 
readPage (i) ; 
itt: 

} 

} 

/* Because I'm only caching a few pages, it's perfectly reasonable to use a 
* simple array and just move elements down in the array to maintain LRU 
* order. For a large cache, something more sophisticated would be 
* appropriate. */ 

DBBTreePage readPage(int pageno) throws IOException { 

// Try to find page in cache, return it if found 
for(int i=@; i< cachePageNumbers.length; i++) { 


_ if (cachePageNumbers[i] == pageno) { 
byte page[] = cachePages [i]; 
if(i>®) { 


// Move this page to front of cache 
System.arraycopy(cachePageNumbers,@, cachePageNumbers,1,i); 
System.arraycopy(cachePages,@, cachePages,1,i); 
cachePageNumbers [9] = pageno; 
cachePages[@] = page; 

} 

// Return found page 

return new DBBTreePage(this, page) ; 
} 


40 


} 
// Page wasn't in cache, read it from disk 
byte page[] = readRawPage(pageno) ; 
// Insert new page at front of cache. 
System. arraycopy(cachePageNumbers,@, 
cachePageNumbers ,1,cachePageNumbers.length-1) ; 
System. arraycopy(cachePages,@, cachePages,1,cachePages.length-1) ; 
cachePageNumbers[@] = pageno; 
cachePages[@] = page; 
return new DBBTreePage(this, page) ; 
} 
/** Convert four bytes from a byte array into an integer, using LSB or MSB 
* data order, as appropriate. 
* @param barray Array of bytes 
* @param offset Offset in barray to read integer 
* @return integer formed from indicated bytes */ 
int bytesToInt(byte barray[],int offset) { 


if (msbFirst) 
return 16777216 * (((int)barray[offset ])&255) + 
65536 * (((int)barray [offset+1])&255) + 
256 * (((int)barray[offset+2])&255) + 
(( (int) barray [offsett+3])&255); 
else 
return (int)barray[offset ])&255) + 


(( 
256 * (((int)barray[offset+1])&255) + 
65536 * (((int)barray[offset+2])&255) + 
16777216 * (((int)barray [offset+3] )&255); 
} 
/** Convert two bytes from a byte array into a short. 
* @param barray Array of bytes 
* @param offset Offset in barray to read short 
* @return short formed from indicated bytes */ 
short bytesToShort (byte barray[],int offset) { 
if (msbFirst) 
return (short) (256 * (((short)barray[offset ])&255) + 
(((short) barray [offset+1] )&255)); 
else 
return (short) ( (((short)barray[offset ])&255) + 
256 * (((short)barray [offsett+1] )&255)); 


Listing Two 


// There doesn't seem to be any one way to open a file that 
// works on all platforms, so this function tries several... 
DBBTree openDatabase(String filename) { 

StringBuffer work; 

DBBTree db; 

// First, try seeing if there's such a thing as a ‘current directory' 

ryt 
db = new DBBTree(new File(filename) ) ; 
System.out.println(" Opened " + filename) ; 
return db; 

} catch (I10Exception e) { 
System.out.println(" 
System. out.println(" 

} 

// Manipulate the document base URL to build a more complete pathname. 

try { 
filename = new java.net.URL(getDocumentBase() ,filename) .getFile(); 

} catch (java.net.MalformedURLException e) { 

// If you can't build a more complete pathname, you're sunk 
return null; 


Couldn't open " + filename) ; 
IOException: " + e); 


} 
// Try filename part of file: URL 
try { 


db = new DBBTree(filename) ; 
System.out.printlin(" Opened " + filename) ; 
return db; 

} catch (IOException e) { 
System.out.println(" 
System. out.println(" 

} 

// Try changing the / to the native separator 

// Note: some platforms lie about the native separator... <sigh> 

work = new StringBuffer (filename) ; 

try { 
char separator = File.separatorChar; 


Couldn't open " + filename) ; 
IOException: " + e); 


System. out.println(" file.separator = " + separator); 
for(int i=0;i<work.length();i++) // Change / to native separator 
if(work.charAt(i) == '/') work.setCharAt(i,separator) ; 


db = new DBBTree(work.toString()) ; 
System.out.println(" Opened " + work); 
return db; 

} catch (IOException e) { 
System.out.println(" 
System.out.println(" 

} 

// Strip first character ... 

filename = filename.substring(1) ; 

try { 
db = new DBBTree(filename) ; 
System.out.println(" Opened " + filename) ; 
return db; 

} catch (IOException e) { 
System.out.printlin(" 
System.out.println(" 

} 

// Everything failed... <sigh> 

return null; 


Couldn't open " + work); 
IOException: " + e); 


Couldn't open " + filename) ; 
IOException: " + e); 


DDJ 
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A powerful and 
extensible graphics 
interface 2D API 





Bill Loeb 


ersion 1.2 of the Java Development 
Kit JDK) includes the Java 2D API— 
a set of functions that is a more 
flexible and full-featured rendering 
package than previous versions of the Ab- 
stract Windowing Toolkit (AWT). The 2D 
API provides enhanced graphics, text 
and image handling, as well as color 
definition and composition, hit detec- 
tion on shapes and text, and device- 
independent printing. 

The 2D API is designed to be extensi- 
ble. The graphics operations of previous 
versions of the API performed a few spe- 
cific functions. The graphics operations 
included in JDK 1.2 expand on that orig- 
inal functionality by supporting more- 
general graphics operations that can be 
extended. 

The advantages of the 2D API are many. 
JDK 1.1 gave you the ability to draw sim- 
ple shapes like rectangles, ellipses, and 
polygons with a single-width line. With 
JDK 1.2, you can draw virtually any shape 
with different line styles, fill styles and tex- 
tures. Two-dimensional transforms can be 
used to translate, rotate, scale, or shear 
any graphical object. Clipping regions can 





Bill is a senior software engineer at 
Stingray Software and can be contacted 
at wloeb@stingray.com. 
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be applied when drawing the shapes. 
Overlapping colors can be blended to- 
gether to create a transparency effect. 

To demonstrate the Java 2D API, I'll start 
with a drawing program that doesn’t use 
the Java 2D API— you could compile and 
run 7ooDee under the JDK 1.1 without 
problems. Listing One presents the Joo- 
Dee class, which extends Canvas and pro- 
vides a white surface on which to draw. 
The main() method just creates a frame 
and sets up its dimensions. The paint() 
method merely takes the standard graph- 
ics context of the canvas and draws a blue 
rectangle on it. 








Adding Java 2D 
So, what does it take to start using the 2D 
API in a class such as TooDee? Not much. 
The 1.2 graphics functionality was designed 
with backward compatibility in mind. 

The 1.2 graphics context class java.awt 
.Graphics2D adds most of the operations 
commonly used to draw shapes. Conve- 
niently, it is derived from the original 
java.awt.Graphics class and maintains all 





The Java 2D API 


of the original functionality. When using 
the JDK 1.2, the Graphics2D object is 
passed into methods like paint(), even 
though the method declaration still shows 
the old Graphics object. Therefore, to use 
the Graphics2D object all you really need 
to do to is cast the Graphics object that 
was passed to a Graphics2D object like 
this: Graphics2D g2 = (Graphics2D)g;. 

Listing Two shows the paint() method 
of the TooDee canvas using the Graph- 
ics2D class to draw our blue rectangle. To 
show that I’m actually doing something 
different, I set the stroke object in the 
graphics context to draw the lines of the 
rectangle with a width of 4. (The stroke 
object in the Graphics2D context deter- 
mines how lines are drawn.) 


Drawing Shapes 

There are three steps to rendering shapes 
in the 2D API. These remain basically un- 
changed from previous versions of the AWT: 


1. Set up the graphics context. 
2. Define the object to draw. 
3. Call one of the rendering methods. 


You can see these three steps in the ex- 
isting paint() method, with the exception 
of the second and third steps, which are 
lumped together in the call to drawkect(). 
To shift the paint() method to use the 2D 
API, start with the graphical objects that 
implement the java.awt.Shape interface. 

The Shape interface is used to define 
geometric shapes for use by the 2D API. 
As long as you implement the methods 
defined by this interface, you can create 
any shape you like. Many common shapes 
are already provided for you in the 
java.awt.geom package, including lines, 
curves, ellipses, rectangles, and rounded 
rectangles. 
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(continued from page 44) 

There are several key methods in the 
Graphics2D class that operate on Shapes. 
The most important to us here is draw(), 
which will draw any Shape using the cur- 
rent settings of the graphics context. The 
paint() method in Listing Three demon- 
strates this by creating a Rectangle2D 
Shape and sending it to the draw() 
method. The paint() method now follows 
the standard three steps. 

There are a couple of things to note 
about the predefined Shapes in the 2D 
API. The first is that the class names all 
end with “2D.” The second is that each 
Shape has two subclasses, one named 
Float and one named Double. This lets 
you choose the precision of the stored 
values. In this case, to use floating-point 
numbers, I chose java.awt.geom.Rect- 
angle2D.Float. Rectangle2D is an ab- 
stract superclass that cannot be instan- 
tiated. 

So what about the java.awt.Rectangle 
object in Listing One? This is a holdover 
from JDK 1.1 and couldn’t possibly im- 
plement the Shape interface, right? Ac- 
tually, while the rectangle object is still 
in the java.awt package in JDK 1.2, it is 
now derived from Rectangle2D, and 
therefore can be passed into new meth- 
ods, such as draw). 
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Stroking Shapes 

The Graphics2D context has an object that 
implements java.awt.Stroke, which deter- 
mines how lines are drawn. Once you set 
the Stroke in the graphics context using 
the setStroke() method, all subsequent 
lines drawn in the graphics context will 
have those characteristics until the Stroke 
is changed again. 

Since Stroke is an interface, you can cre- 
ate your own custom Strokes. There is one 
Stroke object provided for your conve- 
nience —java.awt.BasicStroke, which al- 
lows you to change the most common 
properties of a drawn line, such as the 
line width, the line style (solid, dotted, 
dashed, and so on), the line-end cap style, 
and the line-join style. 

The one major piece of information left 
out of the BasicStroke object is the color 
of the line. This is maintained separately 
by the graphics context with a Paint ob- 
ject, and can be set by calling the set- 
Paint() method. A Paint object is any class 
that implements the java.awt.Paint inter- 
face. Luckily, the java.awt.Color object im- 
plements the Paint interface and you can 
use the colors you are familiar with from 
JDK 1.1. In Listing Three, calling setCol- 
or() still sets the line color. 

Listing Four shows a more advanced 
use of the BasicStroke object. Here, I set 
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up a Stroke object to draw lines with a 
width of 4, a rounded-end cap style, a 
bevel-join style, and a dashing style where 
there are lines of length 20 followed by 
spaces of length 10 (as defined in the 
dash[/ array). I've made the rectangle a 
little bigger so that when the program is 
run, all of the effects are noticeable. The 
rectangle is obviously dashed, the dashed 
lines have rounded ends, and the corners 
of the rectangle are beveled where the 
lines meet. You can play around with the 
values passed into the BasicStroke con- 
structor and witness the effects when 
TooDee is executed. 


Filling Shapes 

Filling Shapes works on the same princi- 
ples as stroking Shapes. The Paint object 
in the graphics context also determines 
how Shapes are filled. To change the fill 
style, you just pass in a new Paint object 
to the setPaint() method of the Graph- 
ics2D object. It is important to note that 
the standard draw() method does not au- 
tomatically fill a Shape for you— it han- 
dles Stroking only. Instead, you need to 
call the separate fill() method, which also 
takes any Shape as a parameter. 

Since Paint is an interface, you can cre- 
ate your own custom fills by creating new 
classes that implement it. There are sev- 
eral Paint objects already available for you 
to work with: a solid color, color gradient, 
and texture paint. 

Filling with a solid color is straightfor- 
ward, since the old java.awt.Color imple- 
ments the Paint interface. In Listing Five, 
all you need to do is call setPaint() with 
the Color of your choice and call flO) 
with the Shape you wish to fill. 

The java.awt.GradientPaint object im- 
plements the Paint interface and provides 
a few useful constructors for setting the 
starting coordinates, starting Color, end- 
ing coordinates, and ending Color of the 
gradient. Listing Six shows the same cir- 
cle from Listing Five being filled, but with 
a color gradient beginning in the top-left 
corner with blue, and then fading to green 
in the bottom-right corner. 

Texture fills are accomplished with the 
help of the java.awt.TexturePaint object. 
A TexturePaint takes a BufferedImage that 
acts as the texture and a rectangle that de- 
fines the area of the BufferedImage to 
replicate for the texture. In the paint() 
method in Listing Seven, you first create 
a BufferedImage in memory and draw a 
simple pattern onto it. Then you create a 
TexturePaint object out of the Buffered- 
Image and add it to the graphics context 
as our Paint object. 

When you were drawing into the 
buffered image’s graphics context, you 
used the old JDK 1.1 methods setColor( ) 
and fillRect(). Remember that Graphics2D 
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is derived from the original Graphics ob- 
ject and you can still use all of its draw- 
ing methods. Whether you use the old 
methods or the new methods is a matter 
of what works for you. In this case, it was 
convenient to make the two calls to /ill- 
Rect( rather than creating two different 
Rectangle2D objects and calling draw() 
on each. 

Another important fact to keep in mind 
is that the same setPaint() method sets 
up the graphics context for both Strokes 
and Fills. Therefore, it makes sense that 
you could draw lines that are drawn with 
textures or gradients. This is exactly what 
is demonstrated in the paint() method in 
Listing Eight. Here, a Stroke of width 10 
is defined so that you can see what is go- 
ing on, and the GradientPaint from List- 
ing Six is used to draw an outline of the 
circle with the blue-green gradient. This 
is a good example of just how flexible the 
2D API is. 


Rendering Hints 

There are a set of options with which you 
can set priorities between rendering speed 
and quality, called “Rendering Hints.” 
These are available so that you can de- 
termine which is more important to your 
Java program — looking better or draw- 
ing faster. All the hints are kept in a sin- 
gle RenderingHint object maintained by 
the graphics context. 

There are many rendering hints, and 
you distinguish between them by pass- 
ing the proper key into the setRender- 
ingHint() method in the graphics con- 
text along with the value to set for the 
hint. The two most commonly used keys 
are KEY_RENDERING and KEY_AN- 
TIALIASING. The former lets you choose 
an overall preference between speed and 
quality, and the latter whether or not to 
smooth out graphics as they are drawn. 
Most of the remaining hints relate to im- 
age processing. 

For example, to set the hint for ren- 
dering quality, you make a call with the 
key and the value: g2.setRenderingHint- 
(RenderingHints.KEY_RENDERING, Ren- 
deringHints. VALUE_RENDER_QUALITY);. 

If you want to set the hint to prefer speed 
to quality, you would pass in RenderingH- 
ints. VALUE_RENDER_SPEED instead. List- 
ing Nine takes the previous gradient stroke 
example and adds in our two hints for qual- 
ity. You should be able to see the differ- 
ence, especially on the interior of the Stroke. 

Not all platforms support all rendering 
hints. The ability of a particular machine 
to implement a hint depends on the avail- 
able hardware. 


Transformations 


Any Shape or image can be drawn trans- 
lated, rotated, scaled, or sheared through 
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the use of a transformation. The graph- 
ics context maintains a java.awt 
geom.AffineTransform object that de- 
termines how the coordinate system of 
the drawing surface will be transformed 
before rendering takes place. Basical- 
ly, an AffineTransform is a two- 
dimensional matrix that transforms the 
values of the geometry being drawn 
from the normal coordinate system into 
a modified one. 

For instance, a rectangle drawn from 
(100,100) to (200,200) without a trans- 
form will be drawn just how you expect. 
However, if you set the transform in the 
graphics context to be rotated by 45 de- 
grees, the coordinates of the rectangle 
will remain the same, but they will be 
transformed to the rotated coordinate 
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space just before the rectangle is drawn. 
This makes it appear at a 45-degree an- 
gle with respect to the origin. 

These transforms are for the entire co- 
ordinate system of the window. This 
means the rotation described earlier will 
rotate the rectangle around the origin, 
which is defined as the top-left corner 
of the canvas. The rectangle will not be 
rotated in place! 

To set the transform in the graphics 
context you must first create and ini- 
tialize an AffineTransform object, and 
then pass it to the setTransform method. 
The AffineTransform object has many 
convenient methods for setting up the 
transformation. Usually, all you need to 
do is call one method, such as rotate(), 
and you are good to go. 
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Listing Ten demonstrates the use of 
transformations by rotating a rectangle 10 
degrees around the origin. 


Creating Custom Shapes 

The Shapes provided by the 2D API are 
sufficient for many programs. If you get 
into more advanced graphics work, how- 
ever, chances are you will need to create 
your own custom shapes. One of the ways 
to do this is to implement the Shape in- 
terface in your own object. You could then 
set up your Shape with whatever geome- 
try you have in mind. 

Another way to make a custom Shape is 
to use the java.awt.geom.GeneralPath ob- 
ject. This is a Shape that lets you piece to- 
gether other Shapes to form a single object. 
This is useful for tacking together lines and 
curves to create a custom outline. 

To add a new Shape to a GeneralPath, 
you call the append() method, which 
takes a Shape to append plus a Boolean 
indicating if the geometry passed in should 
be connected to the existing geometry in 
the GeneralPath. Listing Eleven is an ex- 
ample of two lines and a curve combined 
together to create a custom shape. 

The 2D API also provides a set of op- 
erations that perform constructive-area ge- 
ometry to create new Areas out of two 
existing Shapes. The Area object is an- 
other class which implements the Shape 
interface and can perform the Boolean 
operations add, subtract, intersect, and ex- 
clusive OR. These operations can only be 
performed with Area objects, but it is easy 
to create Areas out of Shapes. 

The Area constructor takes a Shape as 
a parameter and gathers all of the neces- 
sary information from it. Once you have 
two Area objects, you may use the 
Boolean operations to combine the areas. 
The call would look something like: 


areal = new Area(shapel1); 
areal.intersect (new Area(shape2)) 


This would place the results of the 
Boolean intersection in the areal object. 
Listing Twelve shows this technique be- 
ing used to create a square with a circu- 
lar hollow within it. 


Conclusion 

The Java 2D API is a powerful and ex- 
tensible graphics enhancement to the JDK 
that makes life much easier if you have 
advanced graphics needs. It is simple to 
move your JDK 1.1 code to use the graph- 
ics system in the JDK 1.2 because such 
great efforts were made to make the 2D 
API backward compatible. Your existing 
programs will work without problems, but 
you now have the ability to utilize the new 
capabilities. 


DDJ 
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Listing One 


import java.awt.*; 
import java.awt.event.*; 
public class TooDee extends Canvas { 
public TooDee() { 
setBackground(Color.white) ; 


public void paint(Graphics g) { 
g.setColor(Color.blue) ; 
: g.drawRect (100,100,100,100) ; 
public static void main(String argv[]) { 
WindowListener 1 = new WindowAdapter() { 
; public void windowClosing(WindowEvent e) {System.exit(@) ;} 


Frame f = new Frame("Too Dee"); 
f.addWindowListener (1) ; 
f.add("Center", new TooDee()); 


f.pack(); 
f.setSize(new Dimension (400,400) ) ; 
f.show(); 
} 
} 
Listing Two 


public void paint(Graphics g) { 
Graphics2D g2 = (Graphics2D)g; 
g2.setColor(Color.blue) ; 
g2.setStroke(new BasicStroke(4.@f)) ; 
g2.drawRect (100,100,180,100) ; 


e e 
Listing Three 
import java.awt.geom.*; // need the geometry package for Shapes 


public void paint(Graphics g) { 
Graphics2D g2 = (Graphics2D)g; 
// Step 1: Set up the graphics context 
g2.setColor(Color.blue) ; 
alee BasicStroke(4.@f) ); 
/ Step 2: Define the object to draw 
Rectangle2D r = new 

Rectangle2D.Float (100.0f,100.0f,100.0f,100.0f) ; 
// Step 3: Call one of the rendering methods 
g2.draw(r); 


Listing Four 


public void paint(Graphics g) { 

Graphics2D g2 = (Graphics2D)g; 

float dash = { 20.0f, 10.0f }; 

g2.setPaint (Color.blue) ; 

g2.setStroke(new BasicStroke ( 
4.Of, // line width 
BasicStroke.CAP_ROUND, // end cap style 
BasicStroke.JOIN_BEVEL, // join style 


0.0f, // miter limit 
dash, // dash array 
®.Of)); // dash phase 


Rectangle2D r = new 
Rectangle2D.Float (100.0f,100.0f,200.0f,200.0f) ; 
g2.draw(r) ; . 


e e e 

Listing Five 

public void paint(Graphics g) { 
Graphics2D g2 = (Graphics2D)g; 
Ellipse2D e = new Ellipse2D.Float(100.0f,100.0f,100.0f,100.Of) ; 
// draw the interior in blue 
g2.setPaint (Color.blue) ; 
2.fill(e); 
/ draw the outline in red 
g2.setPaint (Color. red) ; 
g2.draw(e) ; 


t] e e 
Listing Six 
public void paint(Graphics g) { 
Graphics2D g2 = (Graphics2D)g; 
Ellipse2D e = new Ellipse2D.Float(100.0f,100.0f,100.0f,100.0f) ; 
GradientPaint gp = new GradientPaint ( 
100.0£, 100.0f, // starting point 


Color.blue, // starting color 
200.0f, 200.0f, // ending point 
Color.green); // ending color 
g2.setPaint (gp) ; 
g2.fill(e); 
g2.setPaint (Color. red) ; 
g2.draw(e) ; 
} 
e e 
Listing Seven 


import java.awt.image.*; // needed for BufferedImage 


public void paint(Graphics g) { 
Graphics2D g2 = (Graphics2D)g; 
Ellipse2D e = new Ellipse2D.Float(100.0f,100.0f,100.0f,100.Of) ; 
BufferedImage bi = new BufferedImage ( 
5, // width 
5, // height 
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BufferedImage. TYPE_INT_RGB) ; // RGB image 
// Get the graphics context of the image and draw into it 
Graphics2D big = bi.createGraphics() ; 
big.setColor(Color.blue) ; 
big. fillRect (@,0,6,6); 
big.setColor(Color.green) ; 
big.fillRect(2,2,4,4); 
// Create the texture from the complete image 
Rectangle2D r = new Rectangle2D.Float (0.0f,0.0f,6.0f,6.0f) ; 
TexturePaint tp = new TexturePaint(bi, r); 


g2.setPaint (tp) ; 


g2.fill(e); 
g2.setPaint (Color. red) ; 
g2.draw(e) ; 
} 
e ° e 
Listing Eight 


public void paint(Graphics g) { 
Graphics2D g2 = (Graphics2D)g; 
Ellipse2D e = new Ellipse2D.Float(100.0f,100.0f,100.0f,100.0f) ; 
GradientPaint gp = new GradientPaint ( 
100.0f, 100.0f, // starting point 


Color.blue, // starting color 
200.0f, 200.0f, // ending point 
Color.green); // ending color 


g2.setPaint (gp) ; 
g2.setStroke(new BasicStroke(10.0f) ) ; 
g2.draw(e) ; 


e e e 
Listing Nine 
public void paint(Graphics g) { 
Graphics2D g2 = (Graphics2D)g; 


g2.setRenderingHint (RenderingHints .KEY_ANTIALIASING, 
RenderingHints .VALUE_ANTIALIAS_ON) ; 
g2.setRenderingHint (RenderingHints.KEY_RENDERING, 
RenderingHints.VALUE_RENDER_QUALITY) ; 
Ellipse2D e = new Ellipse2D.Float(100.0f ,100.0f,100.0f,100.0f) ; 
GradientPaint gp = new GradientPaint ( 
100.0f, 100.0f, // starting point 


Color.blue, // starting color 
200.0f, 200.0f, // ending point 
Color.green); // ending color 


g2.setPaint (gp) ; 
g2.setStroke(new BasicStroke(10.@f)); 
g2.draw(e) ; 


Listing Ten 


public void paint(Graphics g) { 
Graphics2D g2 = (Graphics2D)g; 
Rectangle r = new Rectangle(100,100,100,100) ; 
// Set up a rotation of 10 degrees around the origin. 
// Note that we need to convert from degrees to radians. 
AffineTransform t = new AffineTransform() ; 
t. rotate (10*java.lang.Math.PI/189) ; 
g2.setTransform(t) ; 


g2.setPaint (Color.blue) ; 


g2.fill(r); 
g2.setPaint (Color.red) ; 
g2.draw(r) ; 
} 
° e 
Listing Eleven 


public void paint(Graphics g) { 
Graphics2D g2 = (Graphics2D)g; 


GeneralPath gp = new GeneralPath(); 
Line2D 11 = new Line2D.Float (50.0f,100.0f,100.0f,100.0f) ; 
gp.append(11, true) ; 
CubicCurve2D cc = new CubicCurve2D. Float ( 
100.0f,100.0f, // starting point 
125.0f,125.0f, // control point 1 
150.0f,125.0f, // control point 2 
175.0f,100.0f); // ending point 
gp.append(cc, true) ; 


Line2D 12 = new Line2D.Float(175.0f,100.0£,225.@£,100.0f) ; 
gp.append(12, true); 


g2.setStroke (new -BasicStroke(4.@f) ) ; 
g2.setPaint (Color.blue) ; 
g2.draw(gp) ; ” 


e e 
Listing Twelve 
public void paint(Graphics g) { 
Graphics2D g2 = (Graphics2D)g; 
Rectangle r = new Rectangle(100,100,100,109) ; 
Area a = new Area(r); 


Ellipse2D e = new Ellipse2D.Float(150.0f,150.0£,25.0£,25.0f) ; 
a.subtract(new Area(e)); 


g2.setPaint (Color.blue) ; 
g2.fill(a); 


g2.setPaint (Color. red) ; 
g2.draw(a); 


DDJ 
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Writing JavaBean 








Visual tool, property 
editor, and bean 
Interactions 





Morgan Kinne 


avaBeans are reusable software com- 

ponents that can be manipulated by 

visual programming tools. Tools such 

as Symantec’s Visual Café or IBM’s Vi- 
sualAge for Java let users manipulate the 
properties of a Bean via a Bean’s proper- 
ty sheet. The property must be both read- 
able and writable to allow editing. Visual 
tools typically provide property editors for 
the basic data types built into the language 
as well as some other common types like 
color and font that can be used by third- 
party Beans. Additionally, the JavaBeans 
spec (http://www .javasoft.com/beans/ 
docs/spec.html) defines a set of classes 
that lets you provide their own property 
editors. In this article, I’ll focus on how to 
build property editors and the relation- 
ships between the visual tool, property 
editor, and Bean. For more information 


Morgan is a programmer at IBM and is 
currently a member of the IBM WebSphere 
Studio development team. He can be con- 
tacted at kinnem@us.ibm.com. 
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Property Editors 


on creating beans, see Cliff Berg’s article, 
“How Do I Create a JavaBean?” (DD/J, 
September 1997). 

The java.beans package contains the 
key classes for implementing property ed- 
itors, and essentially provides for three 
types of editors— string, list, and custom. 
With the exception of the custom editor, 
the visual tool handles all aspects of the 


user interface via the Bean’s property 
sheet, so you need only implement logic 
to validate and maintain the property’s 
current value. The PropertyEditor inter- 
face defines the methods that each prop- 
erty editor must implement. The methods 
that need full implementations vary with 
the type of property editor being built. A 
PropertyEditorSupport class that has de- 








fault implementations of all these meth- 
ods is also provided. Property editors nor- 
mally subclass PropertyEditorSupport. 


The PropertyEditor Interface 

The getValue and setValue(Object value) 
methods are used by the visual tool to set 
and retrieve the value of the property. The 
parameter of setValue is an Object, indi- 
cating that properties maintained by the 
Bean as primitives (int, for instance) are 
sent to the property editor as an instance 
of their corresponding wrapper class Un- 
teger). The getAsText and setAsText meth- 
ods perform the same function using 
strings to represent the property’s value. 
Most property editors must be able to pro- 
vide the value of the property as a string. 
The setAsText method must be able to re- 
ceive any string that is returned from getAs- 
Text and convert it to the proper proper- 
ty value. 

Some visual tools, such as JavaSoft’s Java- 
Beans Developers Kit (BDK), maintain the 
state of the Bean and its properties via se- 
rialization. Others, such as IBM’s VisualAge 
for Java, recreate the state of a Bean at 
run time by generating Java code that sets 
the Bean’s properties to the values that 
were specified at edit time. The get- 
JavalnitializationString method supports 
the latter category of tool by returning a 
snippet of Java code that, when execut- 
ed, results in the current value of the prop- 
erty. For example, if a Bean had a prop- 
erty declared as int foo, and its current 
value was 2, this method would return the 
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(continued from page 52) 
string “2.” The tool uses this string to gen- 
erate code like beanInstance.setFoo(2) to 
set the property’s value. 

The getTags method returns an array of 
Strings. When this method returns null, 


Wi és U = KEY : the visual tool uses a String editor in its 


property sheet to allow users to manipu- 

° . late the property’s value. If your proper- 

the Sol ution for U N IX ty assumes a limited set of values, you can 

Nee ete =| return an array containing a string for each 

possible value. Visual tools will present 
this array as a drop-down list. 


isPaintable and paintValue(Graphics g, 
Rectangle r) are used by property editors 


WIBU-KEY supports every platform Types Include: 


from PC and Mac to UNIX and AS/400 


Network Features, 


with effective protection that  @geyies Distribution Features that paint the current value of the prop- 
- #§é«732«LlT # =| erty in the property sheet themselves. 
works through real cx 24 NE £0" Demo Versions When isPaintable returns True, most tools 


invoke the property editor’s paintValue 
method when the property needs to be 
updated in the property sheet. This tech- 
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every property editor must implement an 
addPropertyChangeListener and remove- 
PropertyChangeListener method. The tool 
registers itself as a property-change lis- 
tener so that it will be aware of changes 
in the property’s value. The property ed- 
itor will send the propertyChange(Prop- 
ertyChangeEvent event) message to each 
registered listener whenever the proper- 
ty’s value changes. You will normally use 


Col opt | | the PropertyEditorSupport default imple- 
A: "Ago US 310000: i mentations of these methods. 


CaseAwareTextDisplay Bean 
~~ Transformation Library in C++. Listing One is a ue ie CaseAware- 
ular transformations included. | 7. TextDisplay. It is a subclass of java.awt.Can- 
2 Nig tse — Parses ee | | vas and displays text. It has several prop- 
‘yim | oC erties of various sorts. The font property is 
a simple (unbound) property that is inher- 
ited from Canvas. The other properties in- 
‘Aharon das Softwar | | herited from Canvas are foreground and 
Conversion House Ltd — | | background. This Bean overrides the prop- 
| erty setters, converting them to bound and 

By using Cebat tants | | constrained properties. 

components, developers are The CaseAwareTextDisplay Bean also 
_ able to develop Cobol re- implements some new bound properties: 
engineering tools muchmore | | jeyr, topMargin, leftMargin, and textCase. 
quickly with higher quality. The text property contains the text to be 
Todd Yancey, Fujitsu shown starting at the pixel offsets indicat- 
Software Corp. Inc. | | ed by the topMargin and lefiMargin prop- 
erties. The text is painted using the inher- 
ited font, foreground, and background 
properties. The textCase property is main- 
tained by the Bean as an int and indicates 
whether the text is to be displayed as 
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typed— in uppercase, lowercase, or initial 
caps. I’ll focus on the fextCase property by 
providing different property editors for it. 

A Bean can have an optional BeanInfo 
class, which describes the properties of 
the Bean and identifies their associated 
property editors. When a property editor 
is not explicitly identified in BeanInfo, the 
tool uses the property editors it provides 
for those properties whose data types it 
understands. Therefore, you do not need 
to provide a property editor for many ba- 
sic data types built into Java. 

The CaseAwareTextDisplayBeanInfo 
class (Listing Two) describes the Case- 
AwareTextDisplay Bean. Its getIcon 
method returns a 32x32 color icon for the 
Bean, which is used by many tools as a 
visual representation of the Bean. Its su- 
perclass, SimpleBeanInfo returns null 
from its getMethodDescriptors and get- 
EventSetDescriptors methods, indicating 
that the tool should use default intro- 
spection for discovering its methods and 
events. The getAdditionalBeanInfo 
method returns the superclass’s BeanIn- 
fo so the visual tool will be aware of the 
inherited font property. 

The getPropertyDescriptors method is the 
heart of the CaseAwareTextDisplayBean- 
Info class. It returns an array containing a 
property descriptor for the text, fore- 
ground, background, topMargin, left- 
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Margin, and textCase properties. The lack 
of a statement like pd.setPropertyEditor- 
Class(aClass) when initializing these prop- 
erty descriptors indicates that the visual 
tool should use its default property editor 
for the property’s data type. The method 


The java.beans 
package contains 
the key classes for 

implementing 
property editors 





also merges in property descriptors (in this 
case the font property descriptor) from its 
superclass. Normally, this logic is not 
needed, but it is included here to cir- 
cumvent a problem in Lotus BeanMachine 
1.1, which never invokes getAdditional- 
BeanInfo and would therefore be unaware 
of the Bean’s font property. 
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The getTextCasePropertyDescriptor 
method builds the property descriptor for 
the textCase property. This is implement- 
ed as a separate method in the sample to 
ease subclassing and demonstrate differ- 
ent property editors. The property’s gef- 
ter and setter methods are identified when 
the property-descriptor constructor is in- 
voked. The descriptor is also set to indi- 
cate that this property is bound, not con- 
strained, is not an expert property, and is 
not hidden. Finally, this method sets the 
display name of the property to “case,” 
which will be used to name the property 
when it is shown in a property sheet. I'll 
use case and textCase property inter- 
changeably from this point, depending on 
the context. Keep in mind these refer to 
the same property. 

Although a BeanInfo is technically not 
required for the CaseAwareTextDisplay 
Bean, it illustrates how to implement a 
BeanInfo that uses the tool’s default prop- 
erty editors. 


Building and Using the Beans 

The Beans presented here were all de- 
veloped with JDK 1.1.4 on Windows NT 
4.0. They were tested with JavaSoft BDK 
1.0 - Nov ’97, IBM VisualAge for Java 
Professional Edition, Lotus BeanMachine 
1.1, and Symantec Visual Café for Java 
PDE 2.0. To compile the Beans you will 
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need JDK 1.1.4 or later, which can be 
downloaded from JavaSoft (http:// 
www.javasoft.com/products/jdk/1.1/ 
index.html). To compile the Beans, is- 
sue the following command in a DOS 





User TextField Tool 


Edit-time Bean 
instantiation 


le ee 


window: javac -verbose -deprecation - 
d. * java. 

Once you have successfully compiled, 
you can construct a jar file using this com- 
mand in a DOS window: jar -cfm Case- 
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Figure 2: Message flow for the property editor. 
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AwareTextDisplay.jar Manifest.mf my- 
beans\*.class mybeans\* gif. This com- 
mand uses the Manifest.mf file in Listing 
Three that identifies which classes in the 
jar are Beans. You can test the Case- 
AwareTextDisplay Bean using BeanBox 
by copying the .jar file to the bdk\jars 
subdirectory and launching BeanBox from 
a DOS window. Select the CaseAware- 
TextDisplay Bean and drop it in the Bean- 
Box. Now edit the case property in the 
Property window. Change the value to 1 
and the text will appear in uppercase; 
change the value to 2 and the text will 
appear in lowercase; change the value to 
3, and the text will appear with the first 
letter of each word in uppercase. Using 
any other value will cause the text to ap- 
pear as it was typed in the Property win- 
dow. Notice that the Property window is 
using the default property editor for the 
case property, which in BeanBox is a sim- 
ple TextField. Although the Bean uses an 
int internally to represent this property, 
that is not the best choice for manipulat- 
ing the value in a property sheet. The 
property can only take on a limited set of 
values and without documentation users 
have no idea which values are allowed. 
This can be improved upon by using a 
String property editor. 


String Property Editor 

For illustrative purposes, and convenience, 
I implemented another Bean named Case- 
AwareTextDisplayT (which, along with 
many of the other Beans discussed in this 
article, is available electronically; see “Re- 
source Center,” page 5), that will use a string 
property editor. This Bean subclasses Case- 
AwareTextDisplay and does nothing. It is 
simply a way to create a new Bean class 
that can have a new associated BeanInfo 
class. CaseAwareTextDisplayTBeanInfo sub- 
classes CaseAwareTextDisplayBeanInfo and 
overrides the getTextCasePropertyDescrip- 
tor method. It sends setPropertyEditor- 
Class(Class forName(" mybeans.TextCase- 
TextPropertyEditor")) to the property 
descriptor to indicate that the TextCase- 
TextPropertyEditor class should be used to 
edit the fextCase property. 

This property editor subclasses the 
PropertyEditorSupport class and imple- 
ments only four methods. The tags class 
constant is an array of strings that are 
valid values for the property. The get7Tags 
method returns null to indicate to the vi- 
sual tool that a String editor should be 
used in the property sheet when editing 
this property. The setAsText method is 
called by the visual tool whenever the 
user changes the value of the property. 
The string users enter is passed as the 
parameter. If the string is valid, the edi- 
tor instance sends setValue to itself, pass- 
ing the position of the string in the array 
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as an Integer object. The superclass’s im- 
plementation of setValue updates the val- 
ue of the property and notifies listeners 
(the tool) of the property change. If the 
string is invalid, setAsText throws an IIle- 
galArgumentException. Some tools will 
catch this exception and display a mes- 
sage to users. The getAsText method sim- 
ply uses the current value of the prop- 
erty as an index into the tags array and 
returns the string found there, thus con- 
verting the property value to a string. Fi- 
nally, the getJavalnitializationString 
method returns the current value of the 
property as a string by sending toString 
to the value. Figure 1 shows the com- 
plete message flow. 

After compiling and rebuilding the jar 
file, if necessary, try dropping the Case- 
AwareTextDisplayT Bean in BeanBox. You 
should be able to enter the following strings 
for the case property and see the appro- 
priate results: As Is, Upper Case, Lower 
Case, and First Letter Capitalized. Although 
still not the best solution for the case prop- 
erty, this type of editor would be a good 
approach for a property where users must 
enter a string that is intuitively known be- 
forehand, such as time-of-day. 

As an aside, JavaSoft’s BDK never sends 
getjavalnitializationString because it uses 


Edit-time Bean 
instantiation 


Invoke property getter 


eee Y if 


setValue() 


Property edit time — 
requests to edit eae 


getCustomEditor() 


Adds custom editor to dialog 
and shows dialog 


Code generation time 





serialization. I’ve seen a fair number of 
bad Beans that failed to implement this 
method and therefore do not work in tools 
such as VisualAge for Java, BeanMachine, 
and Visual Café. I suspect that the devel- 
opers of these Beans only tested in Bean- 
Box. Be sure to test your Beans and prop- 
erty editors against multiple tools, 
particularly if your Beans are being de- 
veloped for the commercial market. 


List Property Editor 

The ideal property editor for the 
textCase property would show a list of 
human readable values that the prop- 
erty can assume and let users select 
from the list. Providing such a proper- 
ty editor is done quite easily by sub- 
classing the TextCaseTextPropertyEditor 
class. The CaseAwareTextDisplayL Bean 
and the CaseAwareTextDisplayLBean- 
Info class perform the same function as 
their corresponding, aforementioned 
classes. In this case, the BeanInfo iden- 
tifies the TextCaseListPropertyEditor class 
and subclasses TextCaseTextProper- 
tyEditor as the property editor class. This 
editor overrides the getTags method and 
returns the array of Strings containing the 
valid values the property can take. Be- 
cause an array of Strings is returned, the 
visual tool will use an instance of 


- one 
PropertyEditor User Interface 
ou ais pcan 


> Returns true 
» | Returns true 


Returns a code snippet that will 
produce the property's value 
at run time 


Figure 3: Typical message flow for a custom editor. 
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java.awt.Choice in its property sheet. Fig- 
ure 2 illustrates the complete message 
flow for this property editor. 


Custom Property Editor 

Another acceptable editor for the textCase 
property is a custom property editor, 
which provides its own graphical user in- 
terface for manipulating the property val- 
ue. Because it provides its own user in- 
terface, a custom editor is an excellent 
choice for complex Bean properties. This 
should not be confused with a Bean cus- 
tomizer, which generally lets users ma- 
nipulate all the properties of a Bean. The 
CaseAwareTextDisplayC Bean and the 
CaseAwareTextDisplayCBeanInfo class per- 
form the usual subclassing. 

TextCaseCustomPropertyEditor is the 
property editor class, which uses an in- 
stance of the TextCaseCustomProper- 
tyEditorGUI class and is a subclass of 
java.awt.Panel, to provide the user in- 
terface. The constructor instantiates the 
user interface and registers itself as a Prop- 
ertyChangeListener so it is aware of user 
interactions. It returns True from its szp- 
portsCustomEditor method, which notifies 
the tool that the editor provides its own 
user interface. When users attempt to edit 
the property’s value, the tool creates a di- 
alog frame, adds to it a Done button and 
the instance of TextCaseCustomProper- 
tyEditorGUI returned from getCustomEd- 
itor. The tool then makes the dialog visi- 
ble to users, and users can manipulate the 
property value, clicking the Done button 
when finished. 

The editor also creates an instance of 
the CaseAwareTextDisplayC Bean, which 
is used to paint itself in the visual tool’s 
property sheet. This is a common and con- 
venient technique for user interface Beans 
since they already know how to paint 
themselves. This class returns true from 
isPaintable and implements the paintVal- 
ue method, indicating that the editor can 
do its own painting within the property 
sheet. The tool provides both a Graphics 
object and a Rectangle in which the paint- 
Value method may paint. 

The TextCaseCustomPropertyEditorGUI 
constructor creates a panel with a group 
of four checkboxes, one for each possible 
value the property can assume, and adds 
itself as an item listener to each checkbox. 
Its setValue method updates the user in- 
terface to reflect the new value and informs 
any property-change listeners of the new 
value. Constant forwarding of property- 
change events is prevented by logic in the 
java.beans.PropertyChangeSupport class, 


‘ which does not invoke the listener’s prop- 


ertyChange method when the old value 
matches the new value. The getValue 
method simply returns the index of the cur- 
rently selected checkbox in the array of 
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checkboxes the class maintains. When 
users select a different checkbox the 
itemStateChanged method is invoked, 
and the TextCaseCustomPropertyEdi- 
torGUI instance sends itself a setValue 
passing the index of the newly selected 
checkbox. This causes the property ed- 
itor to be notified of the change that, in 
turn, notifies the visual tool of the 
change. The visual tool will then nor- 
mally invoke paintValue to update its 
property sheet. Figure 3 is a typical mes- 
sage flow for a custom editor. 





Listing One 


package mybeans; 
import java.awt.*; 


import java.beans.PropertyChangeListener; 
import java.beans.PropertyChangeSupport; 
import java.beans.PropertyVetoException; 
import java.beans.VetoableChangeListener; 
import java.beans.VetoableChangeSupport; 


import java.io.Serializable; 


// CaseAwareTextDisplay 


public class CaseAwareTextDisplay extends Canvas implements Serializable 


eee Serene Pe } 


// Class constants 


The TextCaseCustomPropertyEditor class 
also implements the now familiar getAs- 
Text and setAsText methods. Not all tools 
support paintable properties. Visual Café 
2.0 is an example of such a tool. However, 
by providing the getAsText and setAsText 
methods, the editor works properly in Vi- 
sual Café, which uses these methods when 
updating its property sheet. 


Conclusion | 
Given the property editor architecture as de- 
fined in the BeanSpec, and in particular the 
capabilities provided by custom property 


editors, it’s possible to write usable proper- 
ty editors to meet a wide range of needs. 
Implementing property editors that are 
portable between visual tools is a bit more 
difficult due to anomalies and different lev- 
els of support among the tools. However, it 
is generally possible to circumvent these 
problems so that your property editors will 
work in most tools. To ensure you’ve ad- 
dressed all the tool anomalies, be certain to 
test your Beans and property editors with 
the visual tools you plan to support. 
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super. setForeground(newColor) ; 
// Inform bound beans of property change 
firePropertyChange (FOREGROUND, oldValue, newColor) ; 


repaint (); 


catch (PropertyVetoException e) {} 


} 


public void setBackground (Color newColor) { 
Color oldValue = getBackground() ; 


try { 


fireVetoableChange (BACKGROUND, oldValue, newColor) ; 
// Set new color only when change not vetoed. 
super. setBackground(newColor) ; 

// Inform bound beans of property change 


repaint (); 


firePropertyChange (BACKGROUND, oldValue, newColor) ; 


catch (PropertyVetoException e) {} 


public int getTextCase() 
return textCase; 


{ 


public void setTextCase(int textCase) { 
int oldValue = this.textCase; 


public static final int AS_IS = 9; 

public static final int UPPERCASE = 1; 

public static final int LOWERCASE me 2s 

public static final int FIRST_IN_CAPS = 3; 

public static final String TEXT = "text"; 
public static final String TOP_MARGIN = "topMargin"; 
public static final String LEFT_MARGIN = "leftMargin"; 
public static final String FOREGROUND = "foreground"; 
public static final String BACKGROUND = "background"; 
public static final String TEXT_CASE = "textCase"; 
public static final String FONT ini <0) +0 a 


// Instance variables 

// The instance variables for font, foreground and background color 
// are inherited from Canvas. 

protected String text = "default text"; 

protected int topMargin = 4; 

protected int leftMargin = 4; 

protected int textCase = AS_IS; 


protected PropertyChangeSupport propertyListenerSupport; 
protected VetoableChangeSupport vetoListenerSupport; 


// Constructor. All beans must have a no-argument constructor. 
public CaseAwareTextDisplay() { 
this.setSize(180, 30); 
propertyListenerSupport = new PropertyChangeSupport (this) ; 
vetoListenerSupport = new VetoableChangeSupport (this) ; 


// Getters and setters. All properties (except font - which is inherited 
// from Canvas) are bound. Foreground and background color are both bound 


// and constrained. 
public String getText() { 
return text; 


public void setText(String text) { 
String oldValue = this.text; 
this.text = text; 
firePropertyChange(TEXT, oldValue, this.text); 


public int getTopMargin() { 
return topMargin; 


public void setTopMargin(int pixels) { 
int oldValue = this.topMargin; 
this.topMargin = pixels; 
firePropertyChange(TOP_MARGIN, new Integer(oldValue) , 
new Integer (this.topMargin) ) ; 
} 


public int getLeftMargin() { 
return leftMargin; 


public void setLeftMargin(int pixels) { 
int oldValue = this.leftMargin; 
this.leftMargin = pixels; 
firePropertyChange(LEFT_MARGIN, new Integer(oldValue) , 


} 
public void setForeground (Color newColor) { 
Color oldValue = getForeground() ; 
try { 
fireVetoableChange (FOREGROUND, oldValue, newColor); 


new Integer(this.leftMargin)) ; 


this.textCase = textCase; 
firePropertyChange(TEXT_CASE, new Integer(oldValue) , 

new Integer(this.textCase) ) ; 
repaint (); 


// Paint method overrides paint in Canvas. 
public void paint (Graphics g) { 
// Convert the text to the proper case 
String convertedText = getText(); 
if (convertedText == null) 
convertedText =" "; 
switch (textCase) { 
case UPPERCASE: 
convertedText = convertedText.toUpperCase(); 
break; 
case LOWERCASE: 
convertedText = convertedText.toLowerCase() ; 
break; 
case FIRST_IN_CAPS: 
convertedText = convertedText.toLowerCase(); 
char [] temp = convertedText.toCharArray(); 
char previous = ' ''; 
for (int i = 0; i < temp.length; i ++) 


if (previous == ' ') 
temp[i] = Character.toUpperCase(temp [i]) ; 
previous = temp[i]; 


convertedText = new String (temp) ; 
break; 
case AS_IS: 
default: 
// Text should be explicitly left as is, or the value for property 
// is unknown, so make no change to the case of the text. 


} 
// Paint the text 
Rectangle r = getBounds(); 
Font font = getFont(); 
if (font == null) 
font = new Font("Dialog", Font.PLAIN, 12); 
FontMetrics fm = Toolkit. getDefaultToolkit().getFontMetrics(font) ; 


int x = leftMargin; 
int y = topMargin + fm.getAscent() ; 


g.setColor(getBackground()) ; 
g.clearRect(r.x, r.y, r.width, r.height) ; 


g.setColor(getForeground()) ; 
g.setFont (getFont()) ; 
g.drawString(convertedText, x, y); 


// Methods to support bound properties. 
public void addPropertyChangeListener (PropertyChangeListener listener) { 
propertyListenerSupport.addPropertyChangeListener (listener) ; 


public void removePropertyChangeListener (PropertyChangeListener listener) { 


/ Set new color only when change not vetoed. 
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propertyListenerSupport.removePropertyChangeListener (listener) ; 


protected void firePropertyChange(String propertyName, 
Object oldValue, Object newValue) { 
propertyListenerSupport.firePropertyChange (propertyName,oldValue,newValue) ; 


// Methods to support constrained properties. 

public void addVetoableChangeListener (VetoableChangeListener vetoListener) { 
vetoListenerSupport.addVetoableChangeListener (vetoListener) ; 

} 


public void removeVetoableChangeListener (VetoableChangeListener vetoListener) 
vetoListenerSupport. removeVetoableChangeListener (vetoListener) ; 


protected void fireVetoableChange(String propertyName, Object oldValue, 
Object newValue) throws PropertyVetoException { 
vetoListenerSupport.fireVetoableChange(propertyName, oldValue, newValue) ; 
} 
} 


Listing Two 


package mybeans; 
import java.awt. Image; 
import java.beans.BeanInfo; 
import java.beans.IntrospectionException; 
import java.beans.Introspector; 
import java.beans.PropertyDescriptor; 
import java.beans.SimpleBeanInfo; 
// CaseAwareTextDisplayBeanInfo 
public class CaseAwareTextDisplayBeanInfo extends SimpleBeanInfo 
{ 
public static final String BEAN_CLASS_NAME="mybeans.CaseAwareTextDisplay"; 
// Define an icon for the bean. Image must be in the bean's subdirectory 
// in the jar, but the subdirectory is not referred to here since its known 
// from the package (fully qualified class name). 
public Image getIcon(int iconKind) { 
if (iconKind == BeanInfo.ICON_COLOR_32x32) 
return loadImage(getBeanIconString()) ; 
else 
return null; 


// Return the property descriptors 
public PropertyDescriptor[] getPropertyDescriptors() { 


PropertyDescriptor[] pd = new PropertyDescriptor [6]; 
PropertyDescriptor[] superPd; 
PropertyDescriptor[] finalPd; 


try { 
// ei the property descriptor for the text property 
pd[@] = 
new PropertyDescriptor( CaseAwareTextDisplay.TEXT, 
Class.forName (BEAN_CLASS_NAME), "getText", "setText"); 
pd[@] .setBound (true) ; 
pd[@] .setConstrained (false) ; 
pd[®] .setDisplayName("text") ; 
pd[@] .setExpert (false) ; 
pd[@] .setHidden (false) ; 


pd[@].setShortDescription("The text to be displayed.") ; 


area the property descriptor for the topMargin property 
pd[i] = 

new PropertyDescriptor( CaseAwareTextDisplay.TOP_MARGIN, 

Class. forName (BEAN_CLASS_NAME) ,"getTopMargin", "setTopMargin") ; 

pd[1] .setBound (true) ; 
pd[1] .setConstrained (false) ; 
pd[1].setDisplayName("top margin") ; 
pd[1] .setExpert (false) ; 
pd[1] .setHidden(false) ; 
pd{1].setShortDescription("The top margin in pixels."); 


a the property descriptor for the leftMargin property 
pd[{2] = 
new PropertyDescriptor( CaseAwareTextDisplay.LEFT_MARGIN, 
Class.forName(BEAN_CLASS_NAME), "getLeftMargin", "setLeftMargin") ; 
pd[2] .setBound (true) ; 
pd[2] .setConstrained (false) ; 
pd(2].setDisplayName("left margin") ; 
pd[2] .setExpert (false) ; 
pd[2] .setHidden (false) ; 
pd[2].setShortDescription("The left margin in pixels."); 


// oe the property descriptor for the foreground property 
pd[3] = 

new PropertyDescriptor( CaseAwareTextDisplay. FOREGROUND, 

Class .forName (BEAN_CLASS_NAME), "getForeground", "setForeground") ; 

pd[3] .setBound (true) ; 
pd[3] .setConstrained (true) ; 
pd[3] .setDisplayName ("foreground") ; 
pd[3] .setExpert (false) ; 
pd(3] .setHidden (false) ; 
pd[3].setShortDescription("The foreground color for the text."); 


// Build the property descriptor for the background property 
pd[4] = 
new PropertyDescriptor( CaseAwareTextDisplay.BACKGROUND, 
Class. forName (BEAN_CLASS_NAME), "getBackground", "setBackground") ; 
pd[4] .setBound (true) ; 
pd [4] .setConstrained (true) ; 
pd[4] .setDisplayName ("background") ; 


} 


pd[4] .setExpert (false) ; 
pd[4] .setHidden(false) ; 
pd[4] .setShortDescription("The background color for the text."); 


// Build the property descriptor for the textCase property 
pd[5] = getTextCasePropertyDescriptor(); 
} 
catch (Throwable t) { 
t.printStackTrace() ; 
return null; // use default design patterns 


// Get the property descriptors of the superclass. The font property is 
// implemented by Canvas. This logic is needed because some tools 
// do not call getAdditionalBeanInfo. 
try { 
BeanInfo superBeanInfo = 
Introspector.getBeanInfo (Class. forName (BEAN_CLASS_NAME) .getSuperclass()); 
superPd = superBeanInfo.getPropertyDescriptors(); 
catch (Throwable t) { 
t.printStackTrace() ; 
return null; // use default design patterns 
} 
// Add the two sets of property descriptors to a single array 
finalPd = new PropertyDescriptor[superPd.length + pd.length] ; 
for (int i = 0; i < superPd.length; i++) 
finalPd[i] = superPd[i]; 
for (int i = superPd.length; i < (superPd.length + pd.length); i++) 
finalPd[i] = pd[i - superPd.length] ; 
// Return the array of property descriptors 
return finalPd; 


// Return the bean info for the superclasses, excluding the Object class. 
// This handles the font property which is implemented in the Canvas class. 
public BeanInfo[] getAdditionalBeanInfo() { 

try { 

BeanInfo[] bi = new BeanInfo[1]; 

bi[@] = 

Introspector.getBeanInfo(Class.forName (BEAN_CLASS_NAME) .getSuperclass()) ; 

return bi; 

} 

catch (Throwable t) { 

} 


return null; 


// Returns a property descriptor for the textCase property. This is 
// implemented as a separate method solely for convenience in subclassing. 
protected PropertyDescriptor getTextCasePropertyDescriptor() 
throws IntrospectionException, ClassNotFoundException { 
PropertyDescriptor pd; 
pd = new PropertyDescriptor (CaseAwareTextDisplay.TEXT_CASE, 
Class. forName(BEAN_CLASS_NAME), "getTextCase", "setTextCase") ; 
pd.setBound (true) ; 
pd.setConstrained (false) ; 
pd.setDisplayName ("case") ; 
pd.setExpert (false) ; 
pd.setHidden (false) ; 
pd.setShortDescription("Case to use for displaying the text."); 
return pd; 


// Returns the name of the file containing the beans icon. This is 
// implemented as a separate method solely for convenience in subclassing. 
protected String getBeanIconString() { 
return "Earth. gif"; 
} 


Listing Three 


Manifest-Version: 1.0 


Name: mybeans/CaseAwareTextDisplay.class 
Java-Bean: true 


Name: mybeans/CaseAwareTextDisplayC.class 
Java-Bean: true 


Name: mybeans/CaseAwareTextDisplayL.class 
Java-Bean: true 


Name: mybeans/CaseAwareTextDisplayT.class 
Java-Bean: true 


Name: mybeans/ColorConstrainer.class 
Java-Bean: true 


DDJ 
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Consumer device 
application development 
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nformation appliances are personal 
network-connected devices such as 
smart web phones, set-top boxes, per- 
sonal digital assistants, hand-held com- 
puters, and game consoles. Recognizing 
the unique (and often low-resource) re- 
quirements for building these personal 
devices, Sun Microsystems released the 
PersonalJava API for building consumer 
devices with displays. In the first in- 
stallment of this two-part article, we dis- 
cussed what we learned about Personal- 
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Java while developing our Kalos Espres- 
so, a lightweight Java User Interface 
toolkit optimized for low-resource envi- 
ronments. We concluded that the emerg- 





make it possible for many consumers to 
easily and inexpensively get plugged in. 
Consequently, human-factor issues and 
user-interface design will be a key part 
of the consumer device software devel- 
opment cycle. 





This month, we’ll examine the hard- 
ware requirements for PersonalJava ap- 
plications, discuss the embedded operat- 
ing systems that support PersonalJava, and 
put PersonalJava and Kalos Expresso to 
work by developing a phone directory ap- 
plication for a web phone appliance. (The 
complete web phone application is avail- 
able electronically; see “Resource Center,” 
page 5.) 


Embedded Systems and PersonalJava 

Operating systems in the embedded 
world cater to both nonvisual (automo- 
bile braking systems, aeronautical pro- 
cessors, telephone switches, and the like) 
and visual applications (PDAs, set-top 
boxes, information appliances, and so 
on). However, some embedded operat- 
ing systems lack the graphic capabilities 
required to support the Abstract Win- 
dowing Toolkit (AWT) package in Per- 
sonalJava. Implementing an AWT layer 
on top of the native graphical system is 
one of the most difficult and time- 
consuming stages in porting the Java VM 
and libraries to a new platform. Conse- 
quently, while many embedded operat- 
ing systems might support an imple- 
mentation of embedded Java, there are 
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(continued from page 64) 

only a handful today that have complete 
PersonalJava support, including the AWT 
implementation. 

Java lets you develop graphical appli- 
cations and applets, without worrying 
about the low-level details of the hard- 
ware. The platform-dependent implemen- 
tation of the Java VM (along with Java li- 
brary support) abstract this technical layer, 
providing you with a platform-independent 
Java AWT API for developing graphical 
applications. 

The AWT specification includes sev- 
eral heavyweight components— buttons, 
checkboxes, text areas, and the like. 
With their native peers, these AWT com- 
ponents add overhead. Each heavy- 
weight component has a peer, forcing 
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the application to maintain two instances 
of a component. Also, every event that 
passes through the heavyweight com- 
ponent must be redirected through its 
peer. Since these memory and process- 
ing overheads are less than desirable in 
low-resource environments, it is impor- 
tant that you minimize the use of heavy- 
weight components. With Kalos Espres- 
so, our solution was to build a set of 
lightweight components that depend 
only on a subset of necessary AWT 
heavyweight system components (Frame, 
Graphics, Font, and the like). This has 
two advantages: 


e You cut down on memory requirements 
and do away with the overhead associ- 
ated with the peer indirection of events. 























in older client-server 






Pressure Pos, Vel 


ey aed aed 
5 ty ia et ct 





Pressure 













Pressure 















*/*/Pressure 


se ets ytd yates aed aecr 
ee ee 





eo ang bol esti 





e You protect Java applications or ap- 
plets from some of the bugs that might 
exist across different platform Java im- 
plementations of AWT heavyweight 
components. 


It is obvious that the same code should 
behave in a similar manner across plat- 
forms, as long as the underlying Java im- 
plementations perform properly. The dif- 
ferent Java implementations are primarily 
to blame for the differences in applica- 
tion behavior. Although it is not possible 
to remove the dependency from the un- 
derlying Java implementation, it is pos- 
sible to minimize its usage— and that’s 
what we've done with Kalos Espresso. It 
only requires a subset of the AWT to 
function, allowing us to maintain relia- 
bility across platforms. 

Several embedded operating-system 
vendors are working to provide support 
for PersonalJava. Microware’s OS-9, Wind 
River’s VxWorks, and Sun’s ChorusOS 
and JavaOS all ship with complete Per- 
sonalJava support. Future releases of oth- 
ers, such as Lucent’s Inferno, Microtec’s 
VRTX, and Geoworks’s GEOS-SC, will 
also support PersonalJava. The different 
processor/OS combinations supported 
are beyond the scope of this article, but 
such information should be readily avail- 
able from individual operating-system 
vendors. 

To cope with the lack of available re- 
sources, the PersonalJava VM implements 
several optimization features. In fact, Sun 
claims that the PersonalJava VM imple- 
mentation is approximately 30 times faster 
than the JDK 1.1 VM. Recently, several 
manufacturers have announced their in- 
tentions to manufacture processors that 
will improve the execution of the Java VM. 
Most of these chips are slated for market 
in 1999. 

Java is an interpreted language and per- 
formance is a big issue. However, its ad- 
vantages as a secure, scalable, and reli- 
able development platform make it an 
excellent choice for next-generation in- 
formation appliance software. Being aware 
of some basic issues, along with careful 
and intelligent programming, make it pos- 
sible to develop applications that are well- 
suited for consumer device environments. 


The PersonalJava 

AddressBook Application 

Developing embedded applications with 
Java provides you with the advantage 
of not having to learn any system 
specifics. A Java application developed 
in a desktop environment should func- 
tion in the same manner on a consumer 
device. For the purpose of illustration, 
we'll implement a sample application that 
runs on Intel’s StrongArm SA11 processor, 
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running Microware’s OS-9 operating sys- 
tem with full PersonalJava support. Our 
goal is for the application to run well 
on processors with speeds as low as 60 
MHz. Our target is to have something 
that works within 4 MB of memory. If 
the PersonalJava VM resides in ROM and 
requires 2 MB of memory to load, that 
leaves only 2 MB of memory to work with. 

Our available platform has support for 
a variety of input devices— mouse, key- 
board, touch screen, and so on. Microware 
OS-9 supports all of these and provides 
appropriate drivers. If you are using an- 
other embedded operating system, refer 
to its documentation to determine the 
available input-device support. Here, we 
will develop the application assuming we 
have a limited keyboard available and a 
stylus for touch input. As for the display, 
we have available a full-color 5x4-inch 
screen with a maximum resolution of 
320x240 pixels. 

Recall that last month, we examined the 
issues with respect to developing for the 
PersonalJava platform. The following 
points illustrate the implementation of 
those ideas. 


e Double buffering. PersonalJava has a 
mechanism in place where we can 
check whether the PersonalJava plat- 
form natively supports double buffer- 
ing to reduce screen flicker. In the event 
that the system does not support dou- 
ble buffering, we have to provide our 
own functionality. This is available in 
the espial.awt.DoubleBufferPanel class, 
which takes care of the necessary dou- 
ble buffering when placed as close to 
the UI root as possible (for example, 

as the immediate and only child of a 

Frame or Applet and the parent of the 

rest of the UI tree). If the system already 

supports double buffering, espial.awt 

DoubleBufferPanel does nothing more 

than act as a container in the UI tree. 

Touch sensitivity. Many PersonalJava 

devices support input via various point- 

ing mechanisms, the most common be- 
ing through touch-sensitive screens. 

All components in Kalos Espresso are 

positional-input ready and can respond 

to touch input. 

¢ Colors. The platform assumption we 
make here ensures that we do not have 
to worry too much about color restric- 
tions because the platform supports 
multiple colors. This may not be true 
for all platforms and, in the interest of 
general applicability, we choose to use 
specific colors that are visible on most 
devices. 

e File systems. Another benefit of the plat- 
form we have chosen is that a local file 
system is supported via flash cards. In 
a more general application, we would 


take into account the possibility of the 
absence of a local file system. To this 
end, we would draw a distinct line be- 
tween the part of the application that 
uses data and the part that stores data, 
allowing us to later port the applica- 
tion where the same assumptions can- 
not be made. 


An Application Launcher 

To start our web phone application, we 
first develop an application launcher. This 
program supports three applications: an 
e-mailer, phone directory, and scratch pad. 
Of the three, we will only implement the 
phone directory. This is sufficient to demon- 
strate how we use Kalos Espresso to de- 
velop PersonalJava application user inter- 
faces. 





Figure 1 shows the application launcher 
on the full-screen display of the web phone. 
To separate the launcher from each of the 
applications it launches, we’ve built it on a 
distinct colored background. Each icon uses 
an EToolStickyButton, which provides a two- 
state button. Like most components in Ka- 
los Espresso, the sticky button is transpar- 
ent, allowing the background color to show 
through. This is advantageous if the back- 
ground is textured with an image. 

Because each sticky button is a Boolean 
component (a two-state button as defined 
in the BooleanDef class), we are able to use 
the EBooleanGroup class to group the sticky 
buttons. This class allows only one of its 
members to be True (much as java.awt 
.CheckboxGroup can be used with java 
.awt.Checkbox) at any given time. 
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Listing One (which is excerpted from 
PhoneApp.java) illustrates the core of the 
application toolbar functionality. The high- 
lighted lines show how the Boolean group- 
ing was used to achieve the selection mech- 
anism for the application icon buttons. 

When users select any of the icons, the 
appropriate application is launched. In this 
case, We use a java.awt.CardLayout to flip 
between the applications that are loaded 
and initialized at startup. In a commercial- 
ly available web phone, the actual launch- 
ing mechanism would be more involved — 
no application would be loaded until 
explicitly asked for by users. The applica- 
tion would also be kept open until explic- 
itly closed. In our example, we simply flip 
to the right card as users select an applica- 
tion. Since only the phone directory is im- 
plemented, selecting other applications flips 
to a blank card. 


The Phone Directory Application 
One of the most important aspects of an 
application for a consumer device is that 
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editable we use a white background 
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it cannot be based on a look-and-feel, 
such as Windows or Motif. All vendors 
try to brand the UI with their own well- 
researched look-and-feel, which will 
identify a product with the manufactur- 
er. This was a consideration with our 
own applications and one of the prima- 
ry mandates during the design and de- 
velopment of Kalos Espresso. As you can 
see in Figure 2, even though there is 
nothing Windows-like or Motif-like about 
the UI, we haven't given up on usabili- 
ty or intuition. 

To enhance usability, the application 
screen is divided into two regions. We’ve 
chosen green as the application color, and 
various shades are used to provide dif- 
ferent hints to users. For example, the up- 
per region uses a different shade from the 
lower region to separate the overall view 
of the phone directory from the specific 
view of a single record. The third shade 
of green (darker) is used to indicate a re- 
gion that is used to view data (lists, uned- 
itable fields, and so on). As Figure 3 
shows, when fields become editable, we 
use a white background because the as- 
sociation of white with editability is well 
established on most UIs. 

There is, of course, still room for im- 
provement. Entire departments in com- 
panies are dedicated to the research and 
design of user interfaces. Also, not all 
devices can/will support a full-color dis- 
play. We are all familiar with the spinach 
green of the Windows CE and Gameboy 
handhelds, where only two colors are 
available — black and not-black. While 
our application uses specific colors and 
targets the full-color display supported 
by the system running OS-9, our toolk- 
it was developed to be extensible both 
visually and functionally without the 
overhead of most highly generic archi- 
tectures. 

One of the features that we used ex- 
tensively is the Border object. Every con- 
tainer (derived from EContainer) in Ka- 
los Espresso supports borders. These are 
special decorative objects that can be giv- 
en to a container to provide flexible bor- 
ders and background painting without 
building specific containers. All the re- 
gional separators and boxes were creat- 
ed at the container level because none 
of our components draw any borders or 
backgrounds. We call this the separation 
of look-and-feel from core UI function- 
ality, by which we mean that in the case 
of a text-editing field, the basic editing 
and visual feedback of such editing is 
separated from the decorative aspects of 
the component. Our text fields provide 
regions where you can edit text, but that 
do not draw borders around themselves 
or look opaque. Such features are best 
achieved by an application developer 


who has a better idea of the corporate 
look-and-feel than would a third-party 
vendor. 

Listing Two (excerpted from PhoneDir- 
App.java, also available electronically) il- 
lustrates the use of border objects in the 
construction of the phone directory list. 
Note the highlighted lines where the 
beveled border with particular back- 
ground colors is set up. There are two 
ways to provide a specific look-and-feel: 


¢ Using borders and simple layouts to cre- 
ate the desired look-and-feel. 

e Extending the components and em- 
bedding the look-and-feel into them so 
that you don’t have to worry about the 
details of drawing the right box around 
the edit field. 


Even when taking the second approach, 
there is still some UI work that requires us- 
ing the first approach. There is no way to 
avoid using borders and layouts, but it is 
possible to avoid directly extending the 
components. While the layouts provided 
by the JDK is limited, it is still sufficient for 
about 85 percent of UI development, with- 
out ever using the infamous (and unnec- 
essarily tedious) java.awt.GridBagLayout. 

Note that in this application UI, we de- 
signed the telephone button to dial a user- 
selected phone number. However, we 
have not provided the implementation to 
perform the actual dialing. 


Device Storage 

The biggest problem with applications for 
consumer devices is storage. When tack- 
ling this problem, you have some options: 


¢ Local flash-disk storage (usually with a 
file system mapped onto it). 

e Remote disk storage via some network 
with a file system mapped on top (NFS 
based, for example). 

¢ No file-mapped storage at all, but a net- 
work connection available for remote 
data transfers. 


While the first and second options use 
identical storage systems (due to the file 
mapping), the third option can leave you 
stranded. Every application has to be de- 
veloped for a specific storage platform, 
or there must be a distinct separation 
between the storage and management 
of the data from the application itself. 

Obviously, separation is the most effi- 
cient route to pursue, but most separation 
scenarios can result in very strange and 
convoluted means of data access on the 
part of the application that has to use the 
data. To help avoid making such a mess, 
Kalos Espresso provides reader/writer- 
based mechanisms known as “DataSource” 
objects. 
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(continued from page 68) 
Figure 4 illustrates the concepts behind 
a data source. The data source masks the 
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Figure 4: A data source. 
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actual details of the storage, thus two users 
of the data source are happily oblivious 
of the storage mechanism’s device de- 
pendencies. Using the basic concepts of 
reading, writing, and listening (with the 
help of the reader/writer-based synchro- 
nization mechanism), data source users 
can manipulate the desired data without 
worrying about side effects and depen- 
dencies. 

The listbox merely listens for changes 
and, when necessary, reads data. When 
the phone directory application makes 
changes to the data source (by adding, 
deleting, or editing), then the listbox is 
notified. 

There is more than just data-storage 
abstraction occurring here; the separa- 
tion of the manipulation of the data from 
the component that displays the data is 
just as crucial. The application is not 
bound by, or distracted by, the limita- 
tions of the component. Everyone deals 
with the data directly and derives their 
respective responses. 

For the phone directory, we have ex- 
tended one of the ListDataSource (see 
Listing Three) implementations to store 
the PhoneDirkecord objects in memory 
(see PhoneDirRecord.java, also available 
electronically). In a more practical im- 
plementation, we would take into account 





@ Multitasking for x86, 
PowerPC, and ColdFire 


@ x86 Protected Mode 


e Networking 


the requirements of the device and im- 
plement a different data source for each 
storage mechanism. 


Conclusion 

If you look at the web phone’s source 
code, you'll see that there is really no 
system-specific code. This application is 
written completely in Java using the 100 
percent pure Java Kalos Espresso GUI 
toolkit, which is built to suit the re- 
quirements of minimal resource envi- 
ronments. 

From our experience, Java has proven 
to be a feasible language for the em- 
bedded world and, as more embedded 
operating systems begin to support Per- 
sonalJava, the demand for applications 
to enable these devices is going to in- 
crease exponentially. 

While the market for consumer devices 
is much larger than that of the personal 
computer, system resources are much 
lower than traditional PCs and user de- 
mographics are extremely diverse. For 
this reason, we would again like to reem- 
phasize the importance of human fac- 
tors and intelligent programming. 


DDJ 
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smxJVM. Try Java applets in your smx 
application at low cost! smxJVM includes 
Java Virtual Machine, Just In Time compiler, 
and Java libraries, including AWT. 





e File System, DOS-Compatible 
Graphical User Interface 
Debugger, Tool, and Board Support 
® DOS & Windows Emulation 
NO ROYALTIES @ 6 MO FREE SUPPORT e 30-DAY FREE TRIAL 


MICRO DIGITAL 1-800-366-2491 www.smxinfo.com/rjdd.htm 
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Listing One 


EBooleanGroup bg = new EBooleanGroup (); 
// setting up Sticky Button 
m_email = new EToolStickyButton (); 
m_email.setBooleanGroup (bg); 
m_email.setState (true) ; 
m_email.setImagePosition (EToolStickyButton.TOP) ; 
m_email.setImageBundle (ImageUtils.getImageBundledResource 
(getClass(), "email.gif")); 
// ending setup of m_email 
container_1.add (m_email) ; 
// setting up Sticky Button 
m_directory = new EToolStickyButton (); 
m_directory.setBooleanGroup (bg); 
m_directory.setState (false) ; 
m_directory.setImagePosition (EToolStickyButton.TOP) ; 
m_directory.setImageBundle (ImageUtils.getImageBundledResource 
(getClass(), "directory.gif")); 
// ending setup of m_directory 
container_1.add (m_directory) ; 
// setting up Sticky Button 
m_scratch = new EToolStickyButton (); 
m_scratch.setBooleanGroup (bg); 
m_scratch.setState (false) ; 
m_scratch.setImagePosition (EToolStickyButton.TOP) ; 
m_scratch.setImageBundle (ImageUtils.getImageBundledResource 
(getClass(), "scratchpad.gif")) ; 
// ending setup of m_scratch 
container_1.add (m_scratch) ; 


Listing Two 


// setting up List 

m_phoneDirData = new PhoneDirListDataSource (); 
m_dirList = new EListBox (m_phoneDirData) ; 

// setting up wrapper for EList 

EPanel tmp_@ = new EPanel (); 

BaseBorder tmp_1; 

tmp_@.setLayout (new BorderLayout ()); 

EScrollPanel sp_@ = new EScrollPanel (m_dirList) ; 
tmp_@.add (sp_@, BorderLayout.CENTER) ; 

tmp_@.setBorder (tmp_1 = new BevelBorder (new Color (89,165,118), false)); 
EScrollbar tmp_2 = new EScrollbar (EScrollbar.VERTICAL) ; 
tmp_@.add (tmp_2, BorderLayout.EAST) ; 
sp_O.setVerticalScrollbar (tmp_2) ; 


Listing Three 


package espial.demo.phoneapp; 


import espial.awt.item.*; 
import espial.util.*; 
import espial.image.*; 


import espial.datasource.list.*; 
import java.awt.*; 


/** A specialized data source which stored PhoneDirRecord entries. This 
* implementation stores the list in memory and as a result the data is 
* non-persistent. The idea here is that by re-implementing this class it is 
* possible to modify the backend data source for the phone directory without 
* the directory being any wiser. 
rs rely on the DefaultListDataSource object to manage the data in memory. 
* 
public class PhoneDirListDataSource extends DefaultListDataSource { 
ImageBundle m_icon; 
public PhoneDirListDataSource (ImageBundle icon) { 
m_icon = icon; 
} 
/** Get an instance of espial.awt.item.Item that can render the data 
* at a specific index. 
* Developers note: By subclassing this method and setting the 
* m_renderer member before calling the superclass method allows the 


* subclass to override the Item that is used. Be careful though that 
* the Item the assigns is compatible with the one used by the 

* superclass unless you're completely overriding this method. 

* @return an instance of Item. This method does not validate index, 
* so it always returns an instance, even though it may draw nothing. 
*/ 
public Item getDataRenderer (int ix) f{ 


if (m_renderer == null) { 
ImageItem it; 
m_renderer = (it = new ImageItem (m_icon.getImage ())); 
it.setImagePosition (ImageItem.LEFT) ; 
} 
Object data = getData (ix); 
if (data instanceof PhoneDirRecord) { 
m_renderer.setName (((PhoneDirRecord) data) .name) ; 
} 
else { 
m_renderer.setName ("** Bad Record **"); 
} 


return m_renderer; 
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Real-Time Graphics Tools and Charting Tools - New 3.0 Revision 


The new features added to Revision 3.0 are based on 2 % years of extensive customer research into the types of 
applications created using our software tools. Over 250 NEW user callable functions have been added to the software. 


Charting Tools 3.0 - New Features New Axis and Axis Label Functions - Date 
labels, time labels. 


New Plot Types - Contour plotting, Open- 


High-Low-Close, Waterfall, and Candlestick. Misc. New Graph Features - Bit block 
transfers for flickerless updates, add new 


objects to an existing graph, serialization, 
coordinate conversion functions. 


New Printing, Bitmap and Metafile 
Functions - Map graph to printed page, 
bitmap and metafile scatter plots, save graphs 
as a DIB, copy graphs to memory bitmap. 


New Text and Legend Functions - User 
definable legends, multiline text strings. The Real-Time Graphics Tools supports scrolling 


New Features Added to Existing Plot 
Objects - Multi-color plot objects, bitmap and 
metafile scatter plots, line marker skip factor. 


New User Interface Routines - Drag graph 
objects and data points with the mouse, super 
zoom up to 10 simultaneous x and y axes, 
XOR data cursors. 


New Auto-Axes Functions - Auto-axes 
graphs based on multiple datasets, auto-axis a 


single axis, auto-axes group datasets, auto- Real-Time Graphics Tools 3.0-In 
Addition to the Features Added to meters, bit block transfers allow for 
BIG Computer Co s the Charting Tools 


New Real-Time Plot Types - Real-time can have individual channel alarms. 
scatter plots, real-time solid area fills, real- 


time multi-bar scrolling, real-time combination Common to both Charting and Real- 
graphs and dynamic line graphs. 
New Features Added to Existing and 
New Real-Time Plot Types - Bad data 
value handling, alarm colors for scrolling and 
sweep graphs, additional alarm colors added New Example Programs, On-Line Help 
to annunciators, annunciator alarm limits for The Graphics Class Libraries for MFC 
The Charting Tools supports multiple colors within each channel, additional alarm zones for has been updated for MFC 6.0 


axes contour data, auto-axes existing graphs. 





line plots, scatter plots and bar graphs. 





lines, bars, area fills and scatter plot symbols. 


flickerless updates. 
New Alarm Features - Dynamic datasets 


Time Graphics Tools 


Compiler Support - 32-Bit only, Visual 
C++ 5, 6. Visual Basic 5, 6, Delphi 3. 


Product information, datasheets, pricing and demos are found on our web site at www.quinn-curtis.com 
Quinn-Curtis, Inc. - Tel. 781-449-6155 FAX 781-449-6109 
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Java Card 
Application 
Development 





Smart card 
development made easy 





Darryl Barnes 


mart cards are credit-card-like com- 

puting devices used in applications 

ranging from cash replacement for 

pay telephones and vending-machine 
purchases, to security devices for medical 
records and network services. 

As a computing device, smart cards 
(sometimes referred to as “pocket PCs”) cur- 
rently have limited resources. A typical smart 
card, for instance, has an 8-bit processor, 8 
KB of ROM, 8 KB of EEPROM, and 128 
bytes of RAM. This also means that writing 
software for small systems is more akin to 
embedded systems development than to 
desktop or client/server development. Such 
development typically involves proprietary 
platforms, APIs, languages, and environ- 
ments to deal with low-level protocols, mem- 
ory management, and the like. 

Java’s portability and other features of- 
fer a solution to obstacles hindering smart 
card development and acceptance. How- 


Darryl has been a consultant and 
entrepreneur in Silicon Valley for the 
past eight years. He can be reached at 
dbarnes@jsource.com. 
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ever, there is clearly no way that a stan- 
dard Java virtual machine can fit within 
the constraints of the typical smart card 
platform. Consequently, JavaSoft and oth- 
ers have developed the Java Card specifi- 
cation— a subset of Java designed for 
smart card applications. Like standard Java, 





Java Card is a platform defined by a lan- 
guage specification, virtual machine spec- 
ification, and API. Essentially, the Java- 
Card Language Specification (the current 
version is 2.1) and Java Card Virtual Ma- 
chine (JCVM) specification are subsets of 
their standard Java counterparts. Howev- 
er, the Java Card API JCAPI) has little in 
common with the standard Java API. In 
this article, I'll discuss Java Card and pre- 
sent a typical smart card applet. 





Commercially, there are a number of Java 
Card products on the market, including 
Schlumberger’s Cyberflex (http://www 
cyberflex.slb.com/), Gemplus’s GemXpresso 
(http://www.gemplus.com/). Several other 
smart card vendors— including Bull, 
Giesecke & Devrient, Motorola, and De- 
LaRue — have announced plans to release 
Java Card-based systems. (Although not a 
smart card, National Semiconductor’s iBut- 
ton was the first product released to im- 
plement Java Card 2.0. iButton is a micro- 
controller housed in a button-shaped case 
that’s intended to be worn as part of a ring, 
badge, or watch.) Furthermore, companies 
such as IBM, Informix, Oracle, and Visa In- 
ternational have endorsed the Java Card 
specification. 


Why Java on Smart Cards? 

Java is an interpreted object-oriented lan- 
guage that provides a high level of ab- 
straction, but is slower and “fatter” than 
other languages. So why Java, when the 
resource constraints on a smart card are 
severe? 

There is currently no standard lan- 
guage for smart card development. Most 
smart card applications in use today were 
custom developed from the ground up, 
which is a time-consuming process. The 
industry needed to develop an open plat- 
form for smart card application devel- 
opment to facilitate faster growth and de- 
crease time to market. This open platform 
needed to be secure enough for multi- 
ple applications on the card and provide 
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(continued from page 72) 
for post- issuance dynamic downloading of 
application code. 

By using Java as a standard application 
framework, smart card application devel- 
opment is accessible to existing Java de- 
velopers. Time-to-market and application 
development costs will also decrease be- 
cause developers are able to build on top 
of the standard framework as well as lever- 
age extensions that others create. 


Figure 1: Application data units. 


ample 1: The 


Java’s innate security features are also 
appealing for smart card development. The 
virtual machine creates a sandbox for each 
applet, securing them from one another. 
This facilitates the creation of multiappli- 
cation cards. 

Additionally, in the future, Java’s secure 
class-loading mechanism will allow for 
the dynamic downloading of applets. The 
current Java Card specification does not 


yet include this feature, since dynamic 


Example 2: The install) method. 


Example 3: The process() method. 
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Introducing the Industry’s First Highly Optimizing Cross-Compiler Suite for the Java Language 


With the Fast)” compiler suite, you get all the 
benefits of the Java programming language 
without the overhead of a Java Virtual Machine. 
Write your program in Java source code. 
Compile it. Straight to machine code. For the 
most popular 32-bit embedded processors. 
PowerPC, 68K/CPU32, ColdFire, and MeCORE. 


performance, detect run-time errors, and get 
moving to the next winning design. 


DINGY AU DYNAN 


Defining Compiler Performance 


An Integrated Systems Company 


What’s more, Fast) is built on top of Diab Data’s 
industry leading optimization and code 
generation technology. With FastJ, you get the 
fast, compact, stable code you want with the 
ability to mix C/C++ and assembly. And with 
Diab Data’s award-winning RTA Suite, you get 
the tools to analyze and improve program 





USA: Tel: 650.571.1700, Fax: 650.571.9068. Europe: Tel: +49 (0)89.9393. 1191, Fax: +49 (0)89.930.5 184 


© 1998, Diab Data, Inc, All Rights Reserved. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. 
in the United States and other countries. Diab Data, Inc. is independent of Sun Microsystems, Inc. Fast] is a trademark of Diab Data, Inc. 
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(continued from page 74) 
downloading requires bytecode verification, 
which is expensive to do on the card. 


How Does Java Card 

Differ From Java? 

There are differences between Java itself 
and Java Card. Smart card applications, for 
instance, contain fairly basic functionali- 
ty, so multiple thread support is not es- 
sential and would unnecessarily consume 
a lot of space. 

Nor is dynamic class loading included 
in the current specification, although it is 
likely to be included later to enable post- 
issuance downloading of applets. For now, 
classes are statically linked before they are 
loaded onto the card. As a consequence, 
applet code can only reference code on 


Wind ee . 


e Over 50 samples speed your 
path to NT/AWDM device drivers 

e New samples for USB, 1394 
and PCI 

e Wizard generates correct code 
for Power Management and 
Plug and Play 

e New C++ classes and C 
modules 

e Supports Windows 98, NT 4.0 
and NT 5.0 

¢ Over 1100 pages of 
documentation 


Need to handle Windows 2000 
correctly? 


There’s Aas one answer! 


iy Certified 


Solution Provider 


the card itself, and a secure installation 
process is required, which is not yet part 
of the specification. 

Java Card does not provide an explicit 
Java security manager. Instead, the Java Card 
Runtime Environment (JCRE) handles all se- 
curity issues. The JCRE is composed of the 
card operating system and the JCVM. 

Finally, there is no requirement for a 
garbage collector in the JCVM. This has 
huge ramifications in the way the card is 
programmed. And it is the reason that 
cloning is not supported. The Object class 
no longer contains a clone() method, and 
the Clonable interface has been removed. 
Since there is no semantic for deleting ob- 
jects in Java, objects that are allocated re- 
main forever on the heap. So, passing ob- 
jects by value is not practical. 


WinDK™ for Windows CE 


e Bus Master DMA and hardware 
scatter-gather, for the highest 
performance device drivers 


¢ Overlapped 1/0 and 
request queuing 


e Interrupts can 
be transparently 
shared across 
multiple devices 


e Full enumeration 
of ISA, PCI, PCMCIA 
and ISAPNP buses 


Porting your 
NT drivers to CE! 


There’s no easier wey 


~ 


Microsoft® 
Windows’CE 


A Microsoft? Solution Provider and Windows CE System Integrator that works for you! 


1-800-962-2114 
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Current implementations of the JCVM 
use specialized bytecode instructions. (The 
specific bytecodes are not yet specified 
so there is currently only source-code 
compatibility. This will likely change in 
the near future, however.) The reason for 
the special bytecodes is that, because the 
Java stack is 32-bit, everything under the 
hood in a JVM is 32-bit. When a byte is 
placed on the stack it still takes up 32 bits. 
This means that even if you optimize your 
code by changing all of your integers to 
bytes, it will make no difference. On the 
other hand, the JCVM bytecode set con- 
tains full support for smaller, primitive 
types, such as shorts. However, it does not 
support char, double, float, long, or ar- 
rays of more than one dimension. 

The integer primitive type is optionally 
supported, meaning that it is not required 
to be implemented. The reason is speed. 
Doing 32-bit arithmetic on an 8-bit pro- 
cessor can be prohibitively slow. The typ- 
ical smart card CPU runs at only 3.57 MHz. 
Realistically, integers will not be included 
in any of the initial implementations on 
8-bit cards. (GemXpresso used a 32-bit 
chip and does support integers. It is the 
first smart card based on a 32-bit RISC 
processor.) In short, the JCVM has re- 
moved some bytecodes for unsupported 
features and added others to fully support 
smaller types. 

Java Card exceptions use 2-byte rea- 
son codes rather than String-based mes- 
sages, because the JCVM does not sup- 
port String objects. Exceptions now have 
get/setReason( ) methods, and exceptions 
are not generally instantiated directly. In- 
stead, each has a static method called 
throwlt(), which takes a reason code as 
a parameter and then throws the system 
instance of the exception. This saves 
space on the heap. 

The JCAPI is very different from the stan- 
dard Java API. Almost none of the standard 
Java classes are supported, including the 
wrapper classes for the supported primi- 
tive types as well as the String class. The 
JCAPI is composed of one core package 
Gava card.framework) and three extension 
packages (java cardx.framework, java- 
cardx.crypto, and java cardx.crypto.enc). 
The “x” in java cardx stands for extension. 
The core package, java card.framework, 
defines all of the essential classes needed 
to create a Java Card applet. There is no 
relationship between a smart card applet 
and a java.applet.Applet. 

The java cardx.framework contains all the 
classes that deal with the smart card file sys- 
tem. It was originally meant to contain ad- 
ditional nonfile-system-extension classes, 
which is why the name does not contain 
the words “file systems.” The java 
cardx.crypto package contains classes that 
deal with cryptography, and the java 
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cardx.crypto.enc package is meant to con- 
tain exportable encryption algorithms. 


Development Process 
There are five steps involved in the Java 
Card development process: 


1. You can compile your applications us- 
ing any standard Java development en- 
vironment, such as the JDK or Syman- 
tec’s Café. 

2. Because Java Card defines a subset of 
Java, you must check to ensure that only 
features supported by Java Card are pre- 
sent. This step is called “verification.” 

3. After verification, the code is in JVM 
bytecode format, but needs to be con- 
verted to JCVM bytecode. This step is 
called “conversion.” 

4, After conversion, you are ready to load 
the code onto the card. Currently, there 
is no standardized file format for load- 
ing; however, one is in the works. 

5. The final step is installation of the ap- 
plet. This is accomplished via a standard 
ISO 7816-4 INSTALL command. The ISO 
7816 standard defines many aspects of 
smart cards from the physical dimen- 
sions to the transmission protocols and 
common instructions. Although a stan- 
dard command is used, the installation 
process is proprietary: How the file is 
broken up and what security mechanism 
is utilized is unspecified. 


Card/Terminal Communications 
The main communication protocol be- 
tween a smart card and a terminal is called 
“T=0.” Instructions in the protocol are 
called Application Data Units (APDU). An 
APDU (see Figure 1) is composed of a 
5-byte header and a data field, which is 
typically 32 bytes. The first byte in the 
header is the class byte, and the second 
is the instruction byte. The class and in- 
struction bytes uniquely identify the in- 
struction to be performed by the card. The 
next two bytes are instruction-dependent 
parameters, which are referred to as P1 
and P2. The last byte, called “Le,” specifies 
the number of bytes being sent in the data 
field. You will define many of these in- 
structions yourself. However, many are also 
defined in various smart card standards, 
such as ISO 7816-4, EMV, and GSM 11.11. 
There is a master/slave relationship be- 
tween the terminal and card. The card re- 
sponds to an instruction sent from a termi- 
nal, but cannot initiate communications on 
its own. The card ends communication by 
sending a status word. This is a 2-byte code 
indicating success or the type of failure. 
When the card receives an APDU from 
the terminal, it examines the class and in- 
struction codes to determine what action to 
take. The parameter bytes may or may not 
contain information, depending on the in- 


Dr. Dobb’s Journal, February 1999 


struction. Le will be nonzero if there is data 
to be retrieved in the data field. The card 
then sends either data of its own followed 
by a status word, or just the status word. 


The Loyalty Applet 

Listing One is a sample Java Card applet— 
a loyalty application. A loyalty system is 
one where points are accumulated toward 
some reward, like a frequent flyer pro- 
gram. The applet has four functions: val- 
idate PIN, crediting points, debiting points, 
and getting the balance. 

The validate PIN instruction validates a 
PIN value against the value in the card. 
This PIN has to be validated before the 
other instructions can be executed. The 
credit instruction adds the given value to 
the point counter, and the debit instruc- 





tion removes points. The “get balance” in- 
struction returns the current points total 
on the card. 

The class byte for all of the instructions 
in this applet is specified as OxAA. Each 
instruction is identified by a unique in- 
struction byte. For example, INS_GET- 
BALANCE has instruction byte 0x20. In this 
case, when the terminal wants to get the 
balance from the card, it sends an APDU 
of 0xAA20000002. The 0x02 in the last byte 
indicates that the terminal is expecting two 
bytes to be returned from the card. 

The applet is composed of only one 
class. I start with the java card,frame- 
work.Applet class in Example 1. This class 
contains the “lifecycle” methods for the ap- 
plet: installO, select), process(), and de- 
select(). 


Too rushed to optimize? 
Think again...Introducing WhiteBox 3.0 
test optimization and coverage all-in-one. 


Getting your software out the door on time can put 
pressure on quality; that can mean shipping late or 
continually going over budget. 

Test optimization is the solution. With WhiteBox 3.0, 
a complete code analysis and test optimization tool 
consisting of metrics and coverage. WhiteBox 3.0 
allows developers and quality assurance professionals 
to determine where to test, how much to test, and 
when to stop testing, greatly reducing testing costs. 
WhiteBox 3.0 optimizes your testing resources and 
provides metrics to meet your most important project 
quality needs. 

WhiteBox 3.0 is specifically designed to not 
change the build process. It also provides strong 


IDE integration, merging and analysis, reporting 
and exporting, and has an intuitive GUI. In addition, 
WhiteBox 3.0 supports projects written in Java, 
as well as © and €++. And if a project is written 
in all three languages, it provides test optimization 
and coverage across all the source code. Developers 
will also appreciate how WhiteBox 3.0 conveniently 
integrates with Microsoft DevStudio and Symantec’s 
Visual Cafe. 

So don’t let the time-to-market rush affect 
either software quality or project cost. Test smarter, 
test faster, and save money with WhiteBox 3.0. 


VERSION 3.0 





Reliable Software 


Technologies 


21515 Ridgetop Circle, Suite 250 
Sterling, VA 20166 
703-404-9293 © Fax: 703-404-9295 


whitebox@rstcorp.com 


www.rstcorp.com/whitebox ¢ 1-800-824-0022 
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Listing One 


package article; 
import javacard.framework.*; 
public class Loyalty extends Applet 


{ 
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// these attributes are made static because they 
// are referenced in the static install method 
protected static short sPoints = Q; 

protected static byte[] baBuffer; 

// CLA & INS definitions 

public static final byte CLA_LOYALTY = (byte) @xAA; 
public static final byte INS_VALIDATE_PIN = 0x19; 
public static final byte INS_GETBALANCE = 0x20; 
public static final byte INS_DEBIT = 0x3@; 

public static final byte INS_CREDIT = @x40; 


// PIN attributes 

public static final byte PIN_LENGTH = 8; 

protected OwnerPIN pin; 

protected static byte[] baPINValue = {@x@A, OxOB, Ox@A, Ox@B, 


@xOA, Ox@B, OxOA, Ox@B}; 


protected transient boolean zIsAuthorized = false; 


public static void install(APDU _apdu) 


{ 


} 


Loyalty loyalty = new Loyalty(); 


// initialize user PIN 
loyalty.pin = new OwnerPIN((byte)5, PIN_LENGTH) ; 
loyalty.pin.updateAndUnblock(baPINValue, (short)@, PIN_LENGTH) ; 


// register the applet 
loyalty.register(); 


public void process(APDU _apdu) 


{ 


// get reference to apdu buffer 

byte[] baBuffer = _apdu.getBuffer(); 

// verify class 

if (baBuffer [ISO.OFFSET_CLA] != CLA_LOYALTY) 
ISOException.throwIt (ISO.SW_CLA_NOT_SUPPORTED) ; 

// branch to each instruction 

switch (baBuffer [ISO.OFFSET_INS] ) 

{ 
case INS_VALIDATE_PIN: 


TRECK REAL-TIME 


EMBEDDED INTERNET PROTOCOLS 


We know that schedules are always tight, and that you do not 
have time to "port" Internet protocols into your embedded envi- 
ronment (let alone write them from scratch). That does not 
stop marketing people inside your company from asking for In- 
ternet functionality in your new product line that is rolling out 
in the next few weeks. Now you have someone to turn to... 


¢ The FASTEST TCP/IP for Embedded Systems 

¢ Fully TESTED and Qualified 

¢ SMALL Code Footprint 

¢ RFC2000 Compliant 

¢ Processor, RTOS, and Compiler Independent 

¢ Written from "scratch" for Embedded Systems 

° BSD4.4 Sockets Interface 

¢ Base TCP/IP includes TCP, UDP, ICMP, IP, ARP, 
ETHERNET, SLIP, PPP, and PING 

¢ Optional Products include SNMPv1, SNMPv2, SNMPv2c, 
SNMPv3, WebServer, POP3, SMTP, PPP, BootP, DHCP, 
FTP, and Telnet 

¢ NO PORTING REQUIRED 


Treeh 


(800)340-6648 or (513)688-0553 
or visit our web page at www.treck.com 








} 


this.validatePIN(_apdu) ; 
break; 

case INS_DEBIT: 
this.debit (_apdu) ; 
break; 

case INS_CREDIT: 
this.credit (_apdu) ; 
break; 

case INS_GETBALANCE: 
this. getBalance(_apdu) ; 
break; 

} 


protected void validatePIN(APDU _apdu) 


{ 


} 


// get reference to apdu buffer 

baBuffer = _apdu.getBuffer(); 

// get data from terminal 

byte bLe = (byte) _apdu. setIncomingAndReceive(); 

// check length being sent 

if(bLe != PIN_LENGTH) 
ISOException.throwIt (ISO.SW_WRONG_LENGTH) ; 

// validate PIN 

if (pin.check(baBuffer, ISO.OFFSET_CDATA, PIN_LENGTH) ) 
zIsAuthorized = true; 

else 
ISOException.throwIt (ISO.SW_SECURITY_STATUS_NOT_SATISFIED) ; 


protected void debit (APDU _apdu) 


{ 


} 


// check if PIN is validated 
if (!zIsAuthorized) 
ISOException. throwIt (ISO. SW_SECURITY_STATUS_NOT_SATISFIED) ; 
// get reference to apdu buffer 
baBuffer = _apdu.getBuffer() ; 
// get data from terminal 
byte ble = (byte) _apdu.setIncomingAndReceive(); 
// get amount from apdu buffer 
short sAmount = Util.getShort(baBuffer, ISO.OFFSET_P1); 
// don't allow negative balance 
if((sPoints - sAmount) < @) 
sPoints = Q; 
else // debit account 
sPoints = (short) (sPoints - sAmount); 


protected void credit(APDU _apdu) 


{ 


} 


// check if PIN is validated 
if (!zIsAuthorized) 
ISOException. throwIt (ISO.SW_SECURITY_STATUS_NOT_SATISFIED) ; 
// get reference to apdu buffer 
baBuffer = _apdu.getBuffer(); 
// get data from terminal 
byte ble = (byte) _apdu.setIncomingAndReceive() ; 
// get amount from apdu buffer 
short sAmount = Util.getShort(baBuffer, ISO.OFFSET_P1); 
// increment balance 
sPoints = (short) (sPoints + sAmount); 


protected void getBalance(APDU _apdu) 


{ 


// check access permissions 
if (!zIsAuthorized) 
ISOException.throwIt (ISO.SW_SECURITY_STATUS_NOT_SATISFIED) ; 
// get reference to apdu buffer 
baBuffer = _apdu.getBuffer(); 
// put balance value into apdu buffer 
Util.setShort (baBuffer, ISO.OFFSET_CDATA, sPoints); 
// send balance 
_apdu. setOutgoingAndSend(ISO.OFFSET_CDATA, (short) 2); 


DDJ 
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module[i] = 0x00; 
advisebuf[i] = 0x00; 
current_read = 0x00; 


A Complete Instrumentation Platform 





For data acquisition, GPIB, and VXI instrument } 
result = SetCtrlVal (panelHandle, PANEL_CONTROL, testing); 5.0 
, . Power_test (status); Now “ 
control, analysis, and user interface tools that Initialize_coils(bank1); Shipp; 
Test_loose_levels(dma); ng <a 


Test_spec_levels(dma); 
Test_temp (current_read); 
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break; 


everything you need under one roof. } 


return 0; 


No questions, no wild claims, no limitations. 


Just rock-solid, lightning-fast C tools for test. 


Why look anywhere else? 


Put LabWindows/CVI to Your Test! 
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Creating Signed, 








Extending the Java 
security framework 





Paul Brigner 


o you need to use Java for your or- 

ganization’s next intranet project? If 

so, you'll probably want to deploy 

your application in a browser. But 
what about the Java sandbox? Many en- 
terprise applications need to save data to 
the local disk, connect to dedicated ap- 
plication servers, or even make native calls 
to legacy libraries. And what about the 
download time? A 3-MB applet won’t 
make you popular among users waiting 
for downloads and it is never a good move 
to anger network administrators. 

Luckily, Netscape and Microsoft have 
facilities for signed, persistent applet de- 
ployment that extends the Java security 
framework to address issues such as these. 
In this article, I'll show how to develop 
these applets for both Microsoft Internet 


Paul is a senior architect for Digital Focus. 
He can be reached at paulb@digitalfocus.com. 
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Persistent Java 
Applets 


Explorer 4.0 (E4) and Netscape Naviga- 
tor 4.0. The examples I present here (avail- 
able electronically, see “Resource Center,” 
page 5) revolve around an applet that 
writes text from a TextArea component to 
the local file system. 





As you probably guessed, the proce- 
dures and resulting functionality differ 
slightly between Netscape and Microsoft. 
When you load a signed, persistent applet 
with IE4, you are prompted to acknowl- 
edge trust and grant specified privileges 
to the classes being installed. The privi- 





leges you request from users may be very 
granular; for example, the applet in List- 
ing One asks for permission to write to a 
single file (output.txt) on the C: drive. Fig- 
ure 1 shows the initial security warning 
dialog presented to users. Clicking on the 
Permissions hyperlink in the Security 
Warning dialog displays the specific priv- 
ileges being requested. With a positive ac- 
knowledgment, the applet is granted the 
permissions and the user will not be 
prompted again. In this model, all per- 
missions are granted up-front and the ap- 
plet is installed and immediately off and 
running. 

The Netscape model is a little more 
inconvenient for both users and devel- 
opers. The archive installation is trig- 
gered by JavaScript, independent of any 
applet parameters. Redirecting users to 
an installation page, if necessary, is in- 
tuitive. The installation page contains 
JavaScript that installs the software. If 
the archive is updated on the client ma- 
chine, users must restart the browser for 
the new archive to be loaded. Upon 
completion, users are instructed with a 
JavaScript alert message-box to return 
to the applet page after they restart the 
browser. | 

In contrast to IE4 where all permissions 
are acknowledged up-front, Netscape 
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Over 1600 Software 
Publishers use FLEXim 


6 Ways to Higher 
Profitability with 
ectronic Licensing 


Make 40-50% more profit, increase account 
penetration, expand your market and slash 
lost revenues from unlicensed use with 
FLEX/m®(FLEXible License Manager’). 
Software industry analysts forecast that over 
50% of software shipped will use electronic 
licenses within the next 5 years. 


Over 1600 software publishers used FLEX/m’s 
patented technology in shipping over 
$10 billion of software in 1997. 


GLOBEtrotter’s FLEX/m works whether 
your software is distributed via the Internet, 
CD, direct sales, through integrators, or sold 
in a box at retail. Here’s how FLEX/m 
increases profitability 6 ways by enforcing 
or monitoring user compliance with 
licensing terms: 


1 -Slash unlicensed use. Lost revenue is not 
from thieves, but from your customers’ 
unlicensed use. Customers will pay for 
software, but without electronic licensing 


~~” customers don’t know what licenses 


they’re using. 


2 - Better account penetration and customer 
loyalty are critical to strong profitability and 
revenue growth. The right electronic licensing 
policies significantly enhance customer loyalty 
and account penetration. 


3 - More efficient pricing expands your 
available market and allows you to develop 
new types of users. 


4—More effective product evaluation 
programs improve sales productivity and 
reduce the length of the sales cycle. In many 
markets, customers don’t buy until they try a 
‘hands-on’ evaluation. 











5 - Lower manufacturing and distribution 
costs. The problem with software manufac- 
turing is making CDs, shipping, handling 
returns and tracking SKUs. Electronic 
licensing decreases the number of SKUs 

and lowers distribution costs. 


6 — Leverage one sale into the next. 
Electronic licensing lets you use the same 
CD to sell multiple products into your 
customer base. You can also leverage the 
Internet to provide more timely updates 
and better service to your customers. 


So if you’re interested in improving your 
software sales and profitability, talk to 
GLOBEz?rotter. 


For a FREE evaluation kit or to learn 
how software publishers are using 
electronic software licensing 


successfully, visit our website at 
www. flexim.com, or call us at 
888-326-6476. 





GLOBEtrotter 


Electronic Commerce For Software” 


http://www.globetrotter.com 
Email: info@globetrotter.com 
Telephone: 408-445-8100 
888-326-6476 
Fax: 408-445-7760 


FLEX/m and GLOBErrotter are registered trademarks 
and “Electronic Commerce for Software” is a trademark 
of GLOBEtrotter Software. All other trademarks are the 
property of their respective owners. 
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(FILEIO, THREAD, PRINTING, and so on) 
permission types. In Navigator, you call 
enablePrivilege in the netscape.securi- 
ty.PrivilegeManager class. Netscape de- 
fines a multitude of macro, primitive, and 
parameterized targets that enable a group 
of specific privileges. Notice how the per- 
mission calls in Listing One are sur- 
rounded by try/catch blocks so the same 
code can execute in either environment. 
Don’t forget to add the IE and Navigator 
security classes to your classpath for com- 
pilation. For Navigator, add java40.jar from 
<Navigator_Program_Dir>\Java\Classes. 
Include <winnt _dir>\Java\Classes\classes 
.zip for IE. 


Internet Explorer 4.0 

Assuming you already have Internet Ex- 
plorer 4.01 SP1, the first step is to ob- 
tain Microsoft’s SDK for Java Chttp:// 
www.microsoft.com/java/sdk/). In ad- 
dition to an updated Java VM, Microsoft's 
JDK equivalent tools, and documentation, 
you'll find three essential utilities in the 
<SDK-Java>\Bin\PackSign directory: 
PIniEdit, DUBuild, and SignCode. 

You will also need a digital ID for Mi- 
crosoft’s Authenticode Technology. I 
picked up a personal software publish- 
er ID from VeriSign (http://www 
verisign.com/) for a $20.00 annual fee. 
The Certificate Authority will issue to 
you a Certificate (.spc) as well as a pri- 
vate key (.pvk). 

Listing Two is a DOS batch file that au- 
tomates the process of building the 
archive. 

There are only three steps: 


1. Use DUBuild to create a Distribution Unit. 

2. SignCode to add your digital signature. 

3. SignCode again to timestamp the 
archive. 


It seems simple, but there is a lot go- 
ing on behind the scenes. Before you 
run the batch file, you must create sign- 
ing directives with the Permission INI 
File Editor tool called “PIniEdit.” With 
PIniEdit, you specify what sandbox lib- 
erties you require. For this example, I 
loaded HIGH permissions into PIniEdit, 
then specified write access to c:\out- 
put.txt (see Listing Three). These direc- 
tives produce the standard sandbox lim- 
itations with the privilege to write to the 
specified local file. 

In Listing Two, DUBuild is used to cre- 
ate an Open Software Distribution (OSD) 
and package it with the classes you spec- 
ify into a cabinet archive (.cab). If you’ve 
made cabinets with IE3, DUBuild is sim- 
ilar to CABArc, but uses the OSD mani- 
fest instead of .inf files. It is important to 
note that DUBuild and Distribution Units 
are only used by Internet Explorer 4.0. 





Looking for a way to 
integrate data from 
your mainframe, 
midrange or other 
host with the Web? 
ViewMax is a powertul too! 
that allows you to preserve 
and extend your company’s 
current IT investments. 


Need quick access to your hosts? 
ViewMax INSTANT-ON capability converts your "green screens" to 
interactive HTML upon installation. 


Looking to build a simplified web GUI? Integrate 
electronic commerce with your legacy systems? 
Re-engineer your business process? Or integrate 
multiple hosts to one interface? 

ViewMax RAPID APPLICATION DEVELOPMENT ENVIRONMENT allows 
you to build a new interface to your systems, integrating as much or as 
little legacy data as you require. As you navigate your host systems and 
DRAG-AND-DROP host data elements to custom web pages, ViewMax 
AUTOMATICALLY LEARNS the legacy menu navigation, 

using Perl patterns to identify pages and fields. 
And ViewMax gives you hooks at every turn 
for inserting your own Perl — letting you build 
additional functionality into your application. 






But don’t take our word for it. Try it for yourself. 
Download now and integrate your systems in no time 


— or call 888-846-3045. 


ViewMax is the complete solution to your host of problems. 


ViewMax. 


Web-to-Host Integration Tools 
www.modcomp.com/viewmax 


MOBCOMP ©1998. All rights reserved. MODCOMP is a registered trademark and ViewMax is a trademark of MODCOMP, Inc. 





This new Distribution Unit technology is 
powerful and complex. The key issue for 
Java deployment is the concept of the 
namespace. The namespace you specify 
is used by the Java Package Manager to 
create an application namespace layer 
above the namespace of packages and 
classes. With an application namespace, 
there is no concern about class name 
collisions with other software develop- 
ers. This even applies to the classes in 
the anonymous (no package) names- 
pace; but, you must place all anonymous 
classes in a directory called “default” for 
IE to find your classes. For the example 
presented here (available electronically; 
see “Resource Center,” page 5), I placed 
the batch file in the MyApplet project di- 
rectory and the MyApplet.class file in the 
default subdirectory. The next two Sign- 
Code commands in the batch file sign 
and timestamp the archive. You will want 
to consult the SDK documentation for 
details on the parameters. 

Finally, you need to build the applet 
HTML (Listing Four). There are four ap- 
plet parameters —namespace, useslibrary, 
useslibrarycodebase, and useslibraryver- 
sion— that direct IE to check for an in- 
stalled Distribution Unit and download 
it if necessary. 


Navigator 4.0 

For Navigator, you will need a Netscape 
Object Signing digital ID (yes, another 
$20.00 to VeriSign) and Netscape’s SignTool 
(formerly Zigbert; see http://developer 
-netscape.com/software/signedobj/jarpack 
-html). Your ID will automatically be 
loaded into Netscape’s key database as 
part of the CA’s issue procedure. I tend 
to wipe out configurations periodically, 
so I’m careful to export the key from 
Netscape right away. 


As with IE, I built a DOS batch file 
(Listing Five) to automate the Navigator 
archive creation. In the batch file, you 
will notice references to inner and out- 
er jars and corresponding subdirectories 


Before you run 
the batch file, you 
must create 
signing directives 
with PIniEdit 





off of the base project directory. This 
structure parallels the archive that will 
be produced. 

The outer jar contains JavaScript in- 
stallation directives (Listing Six) and the 
inner jar. The inner jar contains the class 
files. Overall, JavaScript plays a critical 
role in Netscape’s LiveUpdate technolo- 
gy. JavaScript in the applet HTML page 
immediately queries the Netscape Client 
Version Registry to see if an installa- 
tion/update is needed and, if so, redi- 
rects users to an install HTML page. Fol- 
lowing the JavaScript logic in the applet 


HTML page (Listing Four), the Netscape 
Client Version Registry is queried for a 
“java/download/ MyApplet” registry en- 
try. The resulting version, if found, is 
compared to a hard-coded netscape sof- 
tupdate.VersionInfo JavaScript object. 
When redirected to the install HTML 
page, the ConditionSoftwareUpdate 
method of netscape.softupdate. Trigger is 
called to install or update the Java soft- 
ware. The install HTML page is linked to 
the outer jar, MyAppletInstall.jar, by the 
parameters to the ConditionalSoftware- 
Update method. 

When the JavaScript triggers the up- 
date, the MyAppletinstall.jar is down- 
loaded to the client. Netscape opens this 
outer jar and processes the install script 
within it (Listing Six). 

The install script creates and/or up- 
dates the entry in the Client Version Reg- 
istry, places the inner jar in the speci- 
fied location, and prompts users to 
restart the browser and reload the ap- 
plet HTML page. I have skimmed over 
the details of the JavaScript objects, but 
you will want to review the documen- 
tation carefully to grasp the true power 
of LiveUpdate (http://developer.netscape 
.com/ docs/manuals/softdist.html). 


Conclusion 

Building signed and persistent applets is 
not a trivial procedure. However, the 
benefits warrant the extra effort. Given 
that Netscape or Internet Explorer are 
standard infrastructure software, they 
provide a convenient platform for de- 
ployment. So for now, we can deal with 
the complexity and redundant proce- 
dures, while waiting for the Java 1.2 Se- 
curity Model. 


DDJ 





Listing One 


import java.awt.*; 
import java.applet.*; 
import java.io.*; 


public class MyApplet extends Applet implements 
java.awt.event.ActionListener 


java.awt.Button button1; 
java.awt.TextArea textAreal; 
public void init() 
i 
setLayout (null) ; 
setSize (300,250) ; 
buttonl = new java.awt.Button("Save") ; 
button1.setBounds(100,175,100,3@) ; 
add(button1) ; 
textAreal = new java.awt.TextArea(); 
textAreal.setBounds(10,10,280,145) ; 
add(textAreal1) ; 


textAreal.setText ("What you type here will be written to\n" + 
"c:\\output.txt when you press the button."); 


button1.addActionListener (this) ; 


} 
public void actionPerformed(java.awt.event.ActionEvent event) 


Object object = event.getSource(); 
if (object == button1) 
{ 


try { 
try { 


if (Class. forName("com.ms.security.PolicyEngine") 


'= null) { 


com.ms.security.PolicyEngine.assertPermission( 


com.ms.security.PermissionID.FILEIO) ; 


} 
} catch (Throwable e) {} 


try { 


if (Class.forName("netscape.security.PrivilegeManager") 


!= null) 


netscape.security.PrivilegeManager.enablePrivilege( 


"UniversalFileWrite"); 


} 
} catch (Throwable e) {} 
FileWriter f = new FileWriter("c:\\output.txt") ; 
f.write(textAreal.getText()); 


f.close(); 


} catch (Throwable e) {} 


Listing Two 


REM MakeCAB.bat 


SET PATH_SAVE=%*PATH% 


SET PATH=%PATH% ; %SDK_BIN% 
SET FRIENDLY_NAME="MyApplet" 
SET NAMESPACE="MyNameSpace" 


SET VERSION="1,0,0,5" 
SET CABFILE=MyApplet.cab 
SET PINI=MyApplet.ini 


SET SDK_BIN=d:\SDK-Java.31\bin\PackSign 


SET CERT_FILE="a:\keys\brigner-msie.spc" 
SET KEY_FILE="a: \keys\brigner-msie. pvk" 
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SET TIME_URL="http://timestamp.verisign.com/scripts/timstamp.d11" IncludeMulticastIPs= 
ExcludeMulticastIPs= 
pause "Copy your classes into the package or default directory" IncludeConnectHosts= 
ExcludeConnectHosts= 
REM build the archive IncludeBindHosts= 
dubuild %CABFILE% . /I *.class /D %FRIENDLY_NAME% /N %NAMESPACE% /V %VERSION% ExcludeBindHosts= 


REM sign the archive 

SET ARGS=-j JavaSign.d1l 

SET ARGS=%ARGS% -jp *PINI% 

SET ARGS=%ARGS% -spc %CERT_FILE% 
SET ARGS=%ARGS% -v %KEY_FILE% 

SET ARGS=%ARGS% -n %FRIENDLY_NAME% 
SET ARGS=%ARGS% %*CABFILE% 

signcode %ARGS% 


REM timestamp the archive 
signcode -x -t *TIME_URL%® -tr 5 %CABFILE% 


REM drop the environment variables 
SET ARGS= 

SET PATH=%PATH_SAVE% 
SET PATH _SAVE= 

SET FRIENDLY_NAME= 
SET NAMESPACE= 

SET VERSION= 

SET CABFILE= 

SET CERT_FILE= 

SET KEY_FILE= 

SET TIME_URL= 

SET SDK_BIN= 

SET PINI= 


pause "Finished!" 


Listing Three 


[com.ms.security.permissions.Filel0Permission] 
Version=2 

IncludeRead= 

ExcludeRead= 

IncludeWrite=c:\output.txt 

ExcludeWrite= 

IncludeDelete= 

ExcludeDelete= 

ReadFileURLCodebase=true 


[com.ms. security. permissions .NetI0Permission] 
Version=2 

IncludeConnectIPs= 

ExcludeConnectIPs= 


IncludeMulticastHosts= 
ExcludeMulticastHosts= 
IncludeConnectGlobalPorts= 
ExcludeConnectGlobalPorts= 
IncludeBindGlobalPorts= 
ExcludeBindGlobalPorts= 
ConnectToFileURLCodebase=false 
ConnectToNonFileURLCodebase=true 


[com.ms.security.permissions.UIPermission] 
Version=2 

ClipboardAccess=false 
TopLevelWindows=true 
NoWarningBanners=false 

FileDialogs=false 

EventQueueAccess=false 


[com.ms.security.permissions.PropertyPermission] 
Version=2 

Unrestricted=false 

AllowedSuffixes=applet 

IncludedProperties= 

ExcludedProperties= 


[com.ms.security.permissions.ReflectionPermission] 
Version=2 

PublicSame=true 

PublicDifferent=true 

PublicSystem=true 

DeclaredSame=true 

DeclaredDifferent=false 

DeclaredSystem=false 


[com.ms.security.permissions.ThreadPermission] 
Version=2 

AllThreadGroups=false 

AllThreads=false 


Listing Four 


<html> 

<head> 
<title>MyApplet</title> 
</head> 


IncludeBindIPs= 
ExcludeBindIPs= 


(continued on page 88) 
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notepad *OUTER_DIR%\%INSTALL_SCRIPT% 


(continued from page 87) 


<body> REM build and sign the outer jar. Specify the install script! 
<p><script LANGUAGE="JavaScript1.2"> SET ARGS=-d *CERT_DIR% 
<!-- Hide from other browsers SET ARGS=%ARGS% -k %CERT% 
if (navigator.appName == "Netscape") { SET ARGS=%ARGS% -Z %OUTER_JAR% 
ref = location.href.substring (@, SET ARGS=%ARGS% -i *INSTALL_SCRIPT% 
location.href.lastIndexOf("/") + 1) SET ARGS=%ARGS% %OUTER_DIR% 
trigger = netscape.softupdate.Trigger Signtool %ARGS% 
version_no = new netscape.softupdate.VersionInfo(1,0,0,@) 
if (version_no.compareTo ( SET ARGS= 
trigger.GetVersionInfo("java/download/MyApplet")) > @) { SET PATH=%PATH_SAVE% 
location = ref + "MyAppletInstall.html" SET PATH_SAVE= 
} SET CERT_DIR= 
} SET CERT= 
// Stop hiding from other browsers --> SET INNER_JAR= 
</script> SET OUTER_JAR= 
<p align="center"> SET INNER_DIR= 
<applet code="MyApplet.class" width="300" height="250"> SET OUTER_DIR= 
<param name="namespace" value="MyNameSpace"> SET INSTALL_SCRIPT= 
<param name="useslibrary" value="MyApplet"> pause "Finished!" 


<param name="useslibrarycodebase" value="MyApplet.cab"> 
<param name="useslibraryversion" value="1,0,0,0"> 
id ae r P si 
</body> 
sa isting 31x 
//Install.js 
// Make sure Java is enabled before doing anything else. 
oe ; if ( navigator. javaEnabled() ) { 
Listing Five // Create a version object and a software update object 
vi = new netscape.softupdate.VersionInfo(1, 0, 8, @); 
REM MakeJAR. bat su = new netscape.softupdate.SoftwareUpdate(this, "MyApplet") ; 
// Start the install process 


SET SDK_BIN=d: \Netscape\bin err = su.StartInstall("java/download/MyApplet", vi, 
SET PATH_SAVE=%PATH% netscape.softupdate.SoftwareUpdate.LIMITED_INSTALL) ; 
SET PATH=%PATH% ; *SDK_BIN% if (err == 0) { 
SET CERT_DIR="D:\nsprofile\paulb" // Find the Java download directory on the user's machine 
SET CERT="Paul Brigner's VeriSign Trust Network ID" JavaFolder = su.GetFolder("Java Download") ; 
SET INNER_JAR=MyApplet.jar // Install the JAR archive. Unpack it and list where it goes 
SET OUTER_JAR=MyAppletInstall.jar err = su.AddSubcomponent("MyApplet", vi, "MyApplet.jar", 
SET INNER_DIR=inner JavaFolder, "", this.force) ; 
SET OUTER_DIR=outer } 
SET INSTALL_SCRIPT=install.js // Unless there was a problem, move JAR archive to final location 
// and update the Client Version Registry 
pause "Copy your class files into the 'INNER' directory." if (err != @) 
su.AbortInstall(); 
REM sign and build the inner jar else { 
signtool -d %*CERT_DIR% -k %CERT% -Z %INNER_JAR% %INNER_DIR% su.FinalizeInstall(); 
alert("Restart your browser and return to this page."); 
REM move the fresh inner JAR into the outer directory } 
del %O0UTER_DIR%\%INNER_JAR% } 


move %INNER_JAR% %OUTER_DIR% 


REM open notepad here to increment the version info number 
pause "Check your version info." DDJ 
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ccording to Microsoft, Visual J++ 6.0 
and the Windows Foundation Class- 
es (WFC) provide Java developers 
with a complete framework for cre- 
ating full-featured and high-quality Win- 
dows applications with Java. The fact that 
WFC applications will run only under Win- 
dows is not a limitation; instead, it allows 
programs to take full advantage of the rich 
functionality that Windows provides. 

On the other hand, Java purists argue that 
WFC is unnecessary. Sun’s standard version 
of Java and the Java Foundation Classes 
(JFC) already provide a framework for de- 
veloping full-featured and high-quality ap- 
plications for Windows and all other plat- 
forms. The purists see WFC as another 
Microsoft ploy to drive developers to 
Windows-only Java extensions and thus 
destroy the cross-platform promise of Java. 

So, does Java have what it takes or is 
WFC the only answer for Java development 
under Windows? In this article, I'll compare 
JFC and WFC by discussing how each was 
used in the development of a real applica- 
tion— an Internet Relay Chat (IRC) chat 
client called “Relay.” For the purposes of 
this article, I define a real application as a 
program that serves a useful function and 
provides a modern GUI complete with tool- 
bars, tool tips, accelerator keys, menus with 
icons, tabbed dialogs, and a Multiple Doc- 
ument Interface (MDI). Source code for the 
sample programs presented in this article is 
available electronically from DD] (see “Re- 
source Center,” page 5).The complete source 
code for both the Relay-JFC and Relay-WFC 
chat-client programs is available electroni- 
cally from http://relayirc.netpedia.net/. 





Chat Client Requirements 

The requirements for the Relay chat client 
are simple. Using Relay, you should be able 
to log into an IRC chat server, join one or 
more chat channels, view messages being 
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sent to those channels, view nicknames of 
users in those channels, and send messages 
to those channels. Relay must do this by 
using the standard IRC protocol as speci- 
fied in Internet RFC1459. Table 1 shows 
these requirements in more detail. 


Chat Engine Architecture 

My first step in the development of Relay 
was the development of a GUI-independent 
chat engine to be reused in both the JFC 
and WFC implementations of the chat client. 
Figure 1 illustrates the class and interface 
relationships that make up the chat en- 
gine architecture. 

The chat engine itself, represented by 
the JChatEngine interface, is responsible 
for managing the connection to the IRC 
server, parsing incoming messages, and 
sending outgoing messages. The chat en- 
gine works with the chat view manager, 
represented by the /ChatViewManager in- 
terface, to ensure that incoming messages 
are displayed in the appropriate views. 

The chat application, represented by 
the /ChatApp interface, manages the user 
interface for the chat client. This includes 
the menus, toolbars, dialogs, and the cre- 
ation of MDI client windows to serve as 
views for each chat channel. The core chat 
engine provides implementations for the 
IChatEngine and IChatViewManager in- 
terfaces. The JFC and WFC versions each 
provide their own implementations of the 
IChatApp and IChatView interfaces. 


JFC Overview 

Sun created the JFC to address the widely 
acknowledged problems with Java’s origi- 
nal AWT user-interface toolkit. AWT was 
based on the native GUI components, 
known as “peers,” of each platform, and 
this caused subtle but problematic varia- 
tions in behavior and look-and-feel from 
platform to platform. JFC addresses this 
problem by avoiding the use of peers al- 
together. JFC components are written in 
pure Java to ensure identical behavior across 
all platforms. JFC provides pure Java or 


lightweight components to replace all of 
the fundamental GUI components found in 
AWT, such as buttons, edits, combo-boxes, 
radio buttons, scrollbars, and menus. 

AWT was also criticized for its “lowest 
common denominator” approach to GUI 
portability. AWT only provided the GUI fea- 
tures that were common to all of its plat- 
forms. JFC addresses this problem by pro- 
viding a rich set of GUI components, 
including table controls, tree controls, im- 
age buttons, internal frames, and a Rich Text 
and HTML-capable text editor framework. 

JFC 1.1 includes the Swing GUI compo- 
nents (see “Java Q&A,” by Mukul Sood, 
DDJ, October 1998), an accessibility API and 
a pluggable look-and-feel architecture. This 
architecture enables applications to dy- 
namically select the Windows, Motif, or the 
new Java look-and-feel at run time. It is also 
possible to develop your own pluggable 
look-and-feel. Due to a licensing issue, the 
Windows look-and-feel is only available on 
Windows platforms. JFC will become part 
of the standard Java Development Kit DK) 
and the run-time environment with the re- 
lease of the JDK 1.2. At that point, JFC will 
be expanded to include a 2D API and drag- 
and-drop support. 


Developing Relay-JFC 

Relay’s user-interface requirements are rel- 
atively straightforward, but fulfilling these 
requirements with AWT would have been 
difficult. Luckily, JFC provides all of the 
components required for Relay. Table 2 
summarizes the components that are used 
in each part of Relay-JFC, and Figure 2 
shows a Relay-JFC running under Windows 
NT. Most of these components are pretty 
standard, run-of-the-mill components that 
need no introduction. I am going to cover 
the more interesting components that were 
used in Relay-JFC: /DesktopPane, JInter- 
nalFrame, AbstractAction, and JTextPane. 


Internal Frames 


The MDI-style interface used by Relay-JFC 
is provided by the JFC internal frames 
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(continued from page 90) 

classes. The major players in the JFC inter- 
nal frame architecture are the /Internal- 
Frame, JDesktopPane, and the Desktop- 
Manager interface. Internal frame windows 
must be derived from the JFC /Internal- 
Frame class. 

The JFC /DesktopPane class serves as a 
container for internal frames, but delegates 
the responsibility of managing the activa- 
tion, opening, closing, dragging, resizing, 
and iconification of the internal frames to a 
DesktopManager interface. You can provide 
your own DesktopManager implementation, 
but you will probably need to do this only 
if you are developing your own pluggable 
look-and-feel. Listing One and Figure 3 pre- 
sent a JFC desktop pane application that 
creates a new internal frame every time you 
press the Add Internal Frame button. 


Actions 

Relay-JFC supports a set of user actions 
such as connect, disconnect, join, and set- 
up. Users may initiate these actions from 


the toolbar or from the main menu. The 
JFC Action interface provides a way to en- 
capsulate such actions so that JFC can 
manage the presentation of toolbar icons, 
menu icons, and tool-tip help text. 

To take advantage of the JFC action ar- 
chitecture, you must provide an imple- 
mentation of the Action interface for each 
user action that your application will sup- 
port. JFC provides a default implementa- 
tion of Action called AbstractAction, which 
supports the standard properties that the 
JFC toolbars and menubars will expect. If 
you derive your action classes from Ab- 
stractAction, then you will only have to 
implement the actionPerformed() method 
for each of your actions. Listing Two and 
Figure 4 present a JFC application that 
uses AbstractAction classes to provide two 
menu items and two corresponding tool- 
bar buttons. 


Text Pane 
One of the requirements for the Relay chat 
client is to display color-coded chat mes- 
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sages. Informational messages, such as 
“HaXXor has left the #raleigh channel” or 
“RaTBoY has quit IRC,” should be displayed 
in a color different than that of the chat con- 
versation. To accomplish this, Relay-JFC 
uses the JFC /TextPane class. /TextPane is 
somewhat complex because it is part of 
a JFC framework for developing viewers 
and editors for HTML, RTF, and similar 
formats. Listing Three and Figure 5 pre- 
sent a JFC /TextPane application that dis- 
plays red text and blue text when you 
press the corresponding buttons. 


JFC Limitations 
Although I found the design of JFC to be 
excellent, I also ran into some serious 
limitations. The most alarming problem 
was probably the overall sluggishness of 
JFC, especially when using internal 
frames. JFC also exhibited some strange 
drawing behavior. For example, when a 
simple yes/no message box is dismissed, 
the whole application is repainted. 
Another limitation is common dialogs. 
Windows provides common dialogs for 
opening files, selecting colors, and choos- 
ing fonts. JFC was originally slated to in- 
clude common dialogs, but due to schedul- 
ing problems they were dropped. Some of 
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Figure 2: Relay-JFC running under Windows NT. 


Dr. Dobb’s Journal, February 1999 


the common dialogs were shipped in the 
com.sun.java.swing.preview package, but 
the font dialog was left out entirely. 

If you have AWT components that you 
wish to reuse with JFC, then be aware of 
another problem. Heavyweight AWT com- 
ponents, like those derived from the Pan- 
el and Canvas classes, do not mix well with 
JFC (for more details, see “Mixing Heavy and 
Light Components,” Java Developers Con- 
nection, http://java.sun.com/products jfc/ 
swingdoc-current/ mixing. html). 


WFC Overview 
Microsoft developed WFC to provide Java 
programmers access to the rich set of GUI 
components and other services of Win- 
dows. WFC is implemented using Microsoft’s 
J/Direct technology, which lets a Java pro- 
gram call individual functions within the 
Windows API. WFC builds upon J/Direct 
to provide an object-oriented interface to 
Windows in the form of a Java class library. 
(See “Examining Microsoft's J/Direct,” by 
Andrew Wilson, DDJ, January 1998.) WFC 
also wraps the HTML object model, so you 
can program HTML forms in the same way 
that they program standard GUI forms. 
By providing wrappers around the 
Windows GUI components and COM in- 
terfaces, Microsoft has been able to pro- 
vide a set of components that match the 
components found in JFC. WFC also al- 
lows access to third-party ActiveX con- 
trols. Windows programmers, whether 
they come from a Visual Basic or MFC 
C++ background, should find WFC fa- 
miliar. 


Developing Relay-WFC 

WFC provides all of the GUI components 
necessary for the Relay chat client right 
out of the box. For every JFC component 
required by Relay-JFC, there is an equiv- 
alent WFC component. Table 3 lists the 
components that are used in each part of 
Relay-WFC, and Figure 6 is Relay-WFC 
running under Windows 95. 


Form 

The WFC Form class is the base class for 
windows and dialogs in WFC. WFC does 
not make a distinction between windows 
and dialogs. A class derived from Form 
can also be used as an MDI client frame 
by simply specifying an MDI container 
Form as its MDI parent. JFC is somewhat 
less convenient. In JFC, frames must be 
derived from /InternalFrame if they are 
to be used within a /DesktopPane. 

The WFC Form class is used as the base 
class for the Relay-WFC main MDI con- 
tainer window, the MDI client chat win- 
dows, and the dialogs. Listing Four and 
Figure 7 illustrate the use of Forms in an 
MDI-style interface. They show a WFC MDI 
application that will create a new MDI frame 
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every time you press the Add New MDI 
Client Frame button. 


Menu 

WFC does not provide anything similar to 
JFC’s Action architecture. In fact, the Ac- 
tion architecture runs counter to the de- 
sign philosophy of WFC. The designer of 
WFC, Anders Hejlsberg, has criticized the 
JDK 1.1 event model because it requires 
you to implement a listener class if you 
want to be notified of an event (see http:// 
msdn.microsoft.com/developer/news/ 
feature/031198/andersh.htm). Implement- 
ing a listener class is not only inconve- 
nient, but also inefficient. Every listener 
is, after all, a class, and classes take up 
memory, disk space, and network band- 
width if used in an applet. 

To allow for more efficient event hand- 
ling in WFC, Microsoft introduced the del- 
egate keyword to Java. A delegate is a 
function pointer that is to be used as a 
callback. WFC lets you register a delegate 
for each event you wish to handle. This 
is similar to the style of event handling 
found in X-Windows and Motif as well as 
Rogue Wave’s zApp. Listing Five and Fig- 
ure 8 present a WFC application that uses 
delegates to implement simple actions for 
two menu items and two corresponding 
toolbar buttons. 


RichEdit 

Where JFC provides a group of classes 
which work together to form a mini frame- 
work for developing text, RTF, and HTML 
editors, WFC just provides a simple Rich 
Text Format control that will meet the 
needs. This control, RichEdit, certainly meets 
the needs of Relay-WFC. Listing Six and 
Figure 9 present a WFC RichEdit applica- 
tion that displays red text and blue text 
when you hit the corresponding buttons. 


Comparing WFC and JFC 

The development of Relay for JFC and 
WFC allowed me to compare the two GUI 
toolkits in terms of variety of components, 
performance, portability, extensibility, and 
tool support. 

Both JFC and WFC support a wide va- 
riety of component types. They provide 
nearly everything that you would expect 
from a GUI class library and more. Cur- 
rently, WFC has a slight edge in this cat- 
egory. I have already mentioned that JFC 
does not provide full support for common 
dialogs. Microsoft’s Internet Controls pack- 
age that ships with WFC also provides a 
number of useful controls that have no 
equivalent in JFC. 

In GUI performance, WFC is the clear 
winner. Take a look at the Relay-JFC and 
Relay-WFC clients running side by side and 
you will immediately see the difference. 
Even with the new dynamic and native 








Table 3: WFC components used in 
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compilers, JFC may still have problems with 
GUI sluggishness because of the overhead 
of its look-and-feel emulation. 

In the area of portability, JFC is the only 
choice. Because JFC is written in pure Java, 
it will run on any of the numerous oper- 








Figure 7: Using Forms in an MDI- 
style interface, AbstractAction classes. 
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Figure 8: WFC application that uses 
delegates. 









ating systems that support a Java JDK 1.1 
or better VM. One of the design goals of 
JFC was to eliminate the subtle differences 
in GUI behavior of AWT. JFC seems to 
have met that goal. There are probably 
some platform-specific incompatibilities, 
but I have worked with JFC under Win- 
dows 95, Windows NT, and Linux and I 
have not encountered any. 

JFC was designed with extensibility in 
mind, and this is clear in almost every part 
of the library. For example, with JFC it’s 
easy to provide your own plug-in editors, 
renderers, and data models for cells with- 
in table controls, items within listboxes, 
and other controls. WFC provides ade- 
quate extensibility, but the individual con- 
trols do not provide as much flexibility as 
those of JFC. I prefer JFC in this area. 
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Figure 9: WFC RichEdit application. 





It appears that both JFC and WFC will 
have excellent tool support. Microsoft will 
provide support for WFC through the Vi- 
sual J++ IDE and GUI builder. Microsoft 
has also lined up numerous third-party 
software vendors to provide WFC com- 
ponents and add ons. Inprise, Symantec, 
and others will be providing full support 
for JFC in their GUI builders, and most 
JavaBean vendors are tooling-up to of- 
fer JFC versions of their products. 


Conclusion 

Even though they seem to have divided the 
Java community, JFC and WFC are signs of 
Java’s growing maturity and suitability for 
real application development. So, which of 
these two Java class libraries is best for you? 
As you might expect, the answer is “it de- 
pends.” JFC is well designed, full featured, 
and a natural next step for developers fa- 
miliar with AWT. If you have cross-platform 
requirements, or suspect that you may have 
such requirements in the future, then JFC 
is your best choice. WFC is fast, full fea- 
tured, and should be familiar territory to 
Windows developers of all stripes. If you 
are specifically targeting the Windows plat- 
form, then WFC is your best choice. 
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Listing One 

import java.awt.*; 
import java.awt.event.*; 


import com.sun.java.swing.*; 
ok 


* Frame with desktop pane and button that creates internal frames. 


*/ 
public class example1 extends JFrame { 


private JDesktopPane _desktop = new JDesktopPane() ; 
private JButton _button = new JButton("Add Internal Frame") ; 


public examplei() ( 
super ("example1") ; 


// Add button in the north and desktop pane in center 
getContentPane().setLayout (new BorderLayout()); 


getContentPane() .add(_button,"North") ; 
getContentPane().add(_desktop,"Center") ; 


public class example2 extends JFrame { 


JMenuBar _menubar 
JToolBar _toolbar 
Action _actionl = 
Action _action2 = 


public example2() { 
super ("example2") ; 


= new JMenuBar() ; 
= new JToolBar(); 
new Action1(); 
new Action2(); 


getContentPane().setLayout (new BorderLayout()) ; 


// Create menu and add actions 


JMenu menu = new JMenu("Menu", false) ; 


menu.add(_action1) ; 
menu.add(_action2) ; 
_menubar.add (menu) ; 


setJMenuBar(_menubar) ; 


// Create toolbar and add actions 
_toolbar.add(_action1); 
_toolbar.add(_action2) ; 


// Add listener to button to create new internal frame 
_button.addActionListener (new ActionListener() { 
public void actionPerformed(ActionEvent e) { 
_desktop.add(new intframe() ,JLayeredPane.PALETTE_LAYER) ; 


getContentPane().add(_toolbar,"North") ; 


// Add listener to window to exit on window close 
addWindowListener (new WindowAdapter() { 

public void windowClosing(WindowEvent e) { 

; System.exit(Q); 
// Add listener to window to exit on window close 


addWindowListener (new WindowAdapter() { a), 
public void windowClosing(WindowEvent e) { // Size and display frame 
System. exit (0) ; seevisible (trie) 
:) } ; setSize (500,400) ; 
// Size and display the frame /** Private inner class for action 1 */ 
sey aibishenne: private class Action1l extends AbstractAction { 


setSize(500,4@9) ; public Action1() { 

} super("Action1") ; 
public static void main(String[] args) { 
new examplel() ; public void actionPerformed(ActionEvent e) { 

} System.out.println("You requested action 1"); 

/** } 

* Internal frame containing a button /** Private inner class for action 2 */ 

*/ private class Action2 extends AbstractAction { 

class intframe extends JInternalFrame { public Action2() { 

public intframe() { super ("Action2") ; 

getContentPane().setLayout (new BorderLayout()); 
getContentPane().add(new JButton("Internal Frame") ) ; 
setSize (200,209) ; 


public void actionPerformed(ActionEvent e) { 
System.out.println("You requested action 2"); 


setVisible(true) ; 
} } 
} public static void main(String[] args) { 
new example2(); 

e e } 
Listing Two } 

import java.awt.*; — 

import java.awt.event.*; Listing Three 

import com.sun.java.swing.*; 
/** import java.awt.*; 

* Frame with menu bar, toolbar and two actions. import java.awt.event.*; 

* / import com.sun.java.swing.*; 
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ar com.sun. java.swing.text.*; 
* 
Faas with text pane and buttons to display red and blue text. 
* 
public class example3 extends JFrame { 
private JTextPane _display = new JTextPane(); 
private JButton _redbutton = new JButton("Add Red Text") ; 
private JButton _bluebutton = new JButton("Add Blue Text") ; 
private StyleContext _styles = new StyleContext(); 


public example3() { 
super ("example3") ; 


// Create panel to hold blue and red buttons 

JPanel buttonpanel = new JPanel(); 
buttonpanel.setLayout (new FlowLayout (FlowLayout .CENTER) ) ; 
buttonpanel.add(_redbutton) ; 
buttonpanel.add(_bluebutton) ; 


// Add button panel in the north and text pane in center 
getContentPane().setLayout (new BorderLayout ()) ; 
getContentPane() .add(buttonpanel ,"North") ; 
getContentPane().add(_display,"Center") ; 


// Define named styles for displaying blue and red text 
Style def = _styles.getStyle(StyleContext . DEFAULT_STYLE) ; 
Style bluestyle = _styles.addStyle("blue", def) ; 

Style redstyle = _styles.addStyle("red", def) ; 
StyleConstants.setForeground(bluestyle, Color.blue) ; 
StyleConstants.setForeground(redstyle, Color.red) ; 


// Add listener to blue button to display blue text 
_bluebutton.addActionListener(new ActionListener() { 
public void actionPerformed(ActionEvent e) { 
display("Here is some blue text\n","blue") ; 


173 
// Add listener to red button to display red text 
_redbutton.addActionListener(new ActionListener() { 
public void actionPerformed(ActionEvent e) { 
display("Here is some red text\n","red") ; 


// Add listener to window to exit on window close 
addWindowListener (new WindowAdapter() { 
public void windowClosing(WindowEvent e) { 
System. exit (@) ; 


}); 

// Size and display the frame 
setSize (500,400) : 
setVisible(true) ; 

} 

/** Display text using specified style */ 

public void display( String text, String style ) { 
Document doc = DeLay getbocuent.(): 
try { 

doc.insertString (doc.getLength() ,text,_styles.getStyle(style) ); 

} 


catch (Exception e) { 
System.out.println("Error displaying text!"); 
e.printStackTrace() ; 
} 
} 
public static void main(String[] args) { 
new example3() ; 


} 


e e 
Listing Four 
import com.ms.wfc.app.*; 
import com.ms.wfc.core.*; 
import com.ms.wfc.ui.*; 
/[** 
rf eae container form with button that creates MDI client frames. 
* 
public class example4 extends Form { 
Container components = new Container () ; 
Button button1 = new Button(); 


public example4() { 
setSize(new Point(300, 300)); 
setText ("example4") ; 
setIsMDIContainer (true) ; 
button1.setDock(ControlDock.TOP) ; 
button1.setText ("Add MDI Client Frame"); 


// Add event handler to button 
button1.addOnClick(new EventHandler (button1_click) ); 


setNewControls(new Control[] { buttoni }); 


} 

/** Handle button click by creating new MDI client frame. */ 

private void button1_click(Object sender, Event e) { 
mdiframe frame = new mdiframe(); 
frame.setMDIParent (this) ; 

' frame.setVisible(true) ; 

public static void main(String args[]) { 
Application. run (new Adan olt) 


} 
/** 


Fe client frame with a button. 

* 

class mdiframe extends Form { 
Container components = new Container(); 
Button buttonl = new Button(); 


public mdiframe() { 
button1.setDock(ControlDock. FILL) ; 
button1.setText ("MDI Client Frame"); 
' this.setNewControls(new Control[] { button1 }); 
} 


Listing Five - 
import com.ms.wfc.app.*; 


import com.ms.wfc.core.*; 
import com.ms.wfc.ui.*; 
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/** 
* Frame with menu bar, toolbar and two actions. 


public class example5 extends Form { 


} 


Container components = new Container() ; 
MainMenu mainMenui = new MainMenu() ; 
MenuItem menuItem1 = new Menultem(); 
MenuItem menulItem2 new MenulItem(); 
MenuItem menuItem3 = new Menultem() ; 
ToolBar toolBari = new ToolBar(); 
Button buttoni = new Button(); 

Button button2 = new Button(); 


tou uw ou 


public example5() { 
setText ("example5") ; 
setSize(new Point (300, 300)); 


// Create menu and add event handlers 

menultem2.setText ("Action1") ; 

menulItem2.addOnClick(new EventHandler(do_action1) ); 
menultem3.setText ("Action2") ; 

menuItem3.addOnClick(new EventHandler(do_action2)) ; 
menultem1.setText ("Menu") ; 

menultem1.setMenuItems(new MenuItem[] {menuItem2, menuItem3}) ; 
mainMenul.setMenuItems(new Menultem[] {menuItem1}) ; 
setMenu(mainMenu1) ; 


// Create toolbar buttons and add event handlers 
toolBar1.setDock(ControlDock.TOP) ; 
button1.setLocation(new Point(@, @)); 
button1.setText ("Action1") ; 
button1.addOnClick(new EventHandler(do_action1)) ; 
button2.setLocation(new Point(75, @)); 
button2.setText ("Action2") ; 
button2.addOnClick(new EventHandler(do_action2) ) ; 


setNewControls(new Control[] { 
button2, 
button1, 
toolBar1}) ; 
} 
private void do_action1(Object sender, Event e) { 
System.out.println("You requested action 1"); 


private void do_action2(Object sender, Event e) { 
System.out.println("You requested action 2"); 


public static void main(String args[]) { 
Application. run (new seaaples ())- 


e e e 
Listing Six 
import com.ms.wfc.app.*; 
import com.ms.wfc.core.*; 
import com.ms.wfc.ui.*; 
/** 
* Shows inserting colored text into a RichEdit control. 


*/ 


public class example6 extends Form { 


Button btnRed = new Button(); 

Button btnBlue = new Button(); 

RichEdit richEdit1 = new RichEdit(); 
Container components = new Container () ; 


public example6() { 
initForm(); 


} 

public void dispose() { 
super.dispose() ; 
components.dispose() ; 

} 

private void btnRed_click(Object source, Event e) { 
appendText ("This is red text\n",Color.RED) ; 


private void btnBlue_click(Object source, Event e) { 
appendText ("This is blue text\n",Color. BLUE) ; 


public void appendText (String str, Color col) f{ 


int begin = richEdit1.getText().length() ; 
richEdit1.select (begin, begin) ; 
richEdit1.setSelColor (col) ; 
richEdit1.setSelText (str) ; 


int end = richEdit1.getText().length(); 
richEdit1.select (end, end) ; 

} 

private void initForm() { 
this.setText ("example6") ; 
this.setAutoScaleBaseSize(new Point(5, 13)); 
this. setBorderStyle (FormBorderStyle.FIXED_DIALOG) ; 
this.setClientSize(new Point(328, 211)); 


btnRed.setLocation(new Point(8, 8)); 
btnRed.setSize(new Point(75, 23)); 

btnRed.setText ("Red Text"); 

btnRed.addOnClick(new EventHandler (this. btnRed_click) ) ; 


btnBlue.setLocation(new Point(88, 8)); 

btnBlue.setSize(new Point(75, 23)); 

btnBlue.setText ("Blue Text"); 

btnBlue.addOnClick(new EventHandler(this.btnBlue_click));. 


richEdit1.setLocation(new Point(8, 40)); 
richEdit1.setSize(new Point(312, 16@)); 


this.setNewControls(new Control[] {richEdit1,btnBlue,btnRed}) ; 


} 
public static void main(String args[]) { 
Application. run (new examples OT 
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PROGRAMMER’S TOOLCHEST 





euse and decoupling are concepts 
fundamental to the object-oriented 
paradigm. In practice, however, 
achieving their promise is easier said 
than done. In this article, I'll present step- 
by-step instructions for making applica- 
tions both reusable and independent us- 
ing a technique called “design by interface.” 

In a nutshell, design by interface means 
you clearly specify the services an object 
offers, separate from its implementation. 
Anyone who uses the object can only call 
on the services in this specification. The 
advantages of design by interface include: 





e Libraries and subsystems can be reused 
without fear of dependencies. 

e Faster, simplified, parallel development. 
Quick-and-dirty implementations can 
be used (and improved later on) if nec- 
essary. Also, independent teams can 
work on different sides of a horizontal 
interface without continually having 
meetings. 

e A guideline for development is sup- 
ported that lets developers of all skill 
levels contribute. 

e The interface can be brought in gradu- 
ally to a software project. 

e Clearer expression and documentation of 
designs are possible. 


Here’s the scenario I was faced with: 
Sending e-mail to users is an easy way for 
programs to give feedback and send warn- 
ings. In the UNIX world, this is common 
and is usually done by starting a sendmail 
process, then passing it the necessary head- 
er and content information. As I began writ- 
ing intranet programs at LION bioscience 
AG (where I work), however, I wanted the 


Robb is a software engineer at LION bio- 
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Specifying object services 
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same functionality in Java that I had with 
our UNIX scripts. 

Initially, I turned to the ORO NetCom- 
ponents class library (http://www.oroinc 
.com/), which was a nearly perfect solu- 
tion. NetComponents is a Java package 
that enables access to the most common- 
ly used Internet protocols —FTP, NNTP, 
SMTP, POP3, Telnet, TFTP, finger, whois, 
and the like, as well as rexec, remd/rshell, 
and rlogin. Because all client classes are 
derived from the NetComponents Socket- 
Client and DatagramSocketClient classes, 
NetComponents presents a consistent API. 
Still, there were several needs that the 
ORO package didn’t address. Conse- 
quently, I ended up writing additional 
classes, which are presented here. 


The Problem 

As a designer/developer, I feel responsi- 
ble for the effects any libraries that I in- 
stall into my company’s development en- 
vironment could have. It’s easy to imagine 
that many applications could make use 
of e-mail services. Dependencies will 
arise between applications written by oth- 
er people and the classes that I install. 
These kinds of dependencies are hard to 
detect and keep track of. Figure 1 shows 
the typical use of the ORO SMTPClient 
and an application. With many different 
applications and programmers using these 
packages, dealing with change becomes 
important. Change is the rule and not the 
exception in software and network de- 
velopment. For example, Javasoft is cur- 
rently working on a JavaMail API. It will 
probably become a standard and an inte- 
grated part of Java. Some third-party li- 
brary developers (including ORO) have 
already promised to conform to it or base 
tools on it. How will large changes in the 
mail system affect the various dependent 
applications? 


Design by Interface 


Another problem with these dependen- 
cies is that class libraries almost always have 
bugs and rough edges that the producers 
want to smooth out. Library upgrades are 
common, and sometimes the API changes 
along with them. And then of course, there 
are the cases where a bug won't be fixed 
soon enough and a module has to be reim- 
plemented in-house. These changes can 
be difficult to make if other systems are 
tied to a particular class library. 

Table 1 is a partial list of the ORO e- 
mail interfaces that have to be learned. 
For the classes to work correctly, you must 
call certain methods and check certain re- 
sults in a specific order. These ordering 
constraints are difficult to remember. Also, 
they expose implementation details — 
users are forced, for instance, to know 
how SMTP works. Maybe future e-mail 
systems (or an e-mail system at 4 differ- 
ent site) won’t use SMTP to send e-mail. 

That the interface is low-level means 
that you will have to repeatedly make the 
same sequences of low-level calls. Sure, 
some applications might need access to 
some low-level features, but I’ve found 
that nine times out of ten, e-mail (from 
applications) is used in one basic way — 
a letter has a sender, subject, some recip- 
ients, and a short message. 

Another way to look at this issue is that 
application programmers should be spend- 
ing their time developing applications, not 
making infrastructure components use- 
able. In most cases, sending e-mail is just 
one small part of a program’s function, 
and shouldn’t require the developer to 
master the details of a particular package, 
or SMTP. 

Most organizations have tight schedules 
and several projects simultaneously un- 
derway. This was true for this case as well. 
We could not wait for weeks while I 
looked for the ultimate e-mail solution. I 
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(continued from page 906) 
needed to find a reasonable solution fast 
to let other projects keep on going. 


The Solution 


The first step is to sit back and imagine 
how you'd like to send e-mail from Java 
if you could. What kind of object or ob- 
jects would you have? What methods 
would they have? How would they be 
named? There are good guidelines avail- 
able for making these kinds of decisions. 
In Object Oriented Software Construction, 
Second Edition (Prentice Hall, 1997), 
Bertrand Meyer suggest a common, clear 
way to work with objects: 


e Create the required objects. 

e Set up any of their properties that dif- 
fer from defaults. 

e Apply the operations you need. 


For the sake of example, I’ll assume 
that I need just one object— an e-mail 
message. First, I instantiate it. Then I send 
some simple messages to it like “set 
sender,” and “set subject.” The message 
for specifying the recipients would be 
like “add recipient,” which makes it clear- 
er that multiple recipients are allowed. 
Finally, I tell the e-mail message to send 
itself. 

The next step is to convert this natural- 
language description into terms comput- 
ers can understand, by writing the equiv- 
alent Java interface. The EmailMessage java 
interface (see Figure 2 and Listing One), 
for instance, is both a description of how 
to use the e-mail subsystem, as well as a 
contract that specifies what services it will 
provide. 

There are a couple of things to note 
here. First, the interface is public — it can 
be seen and used by anyone. This is en- 
forced by Java, and will be handy later. 
Second, exceptions are specified in the 











Application SMTPClient 


Figure 1: The typical relationship 
between the ORO SMTPClient and a 
application. | 


interface 
EmailMessage 


setSender 
addRecipient 
addCC 
setContent 
setSubject 
send 


Figure 2: The EmailMessage interface. 
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Table 1; Partia 


interface. This is important because a full 
interface specifies not only the inputs and 
outputs of a class, but also the error con- 
ditions. Finally, it is fully documented — 
the interface will become the user’s view 
into the e-mail subsystem, and is why doc- 
umentation is so important here. 

The third step is write a package- 
visible adapter for your current e-mail im- 
plementation. OROEmailAdapter.java (List- 
ing Two), for instance, is an “adapter’— 
something that works between our nice 
e-mail interface and the actual e-mail sub- 
system. Simply put, an adapter converts 
one interface to another. Here’s where I’ve 





interface 
EmailMessage 


setSender 
addRecipient 
addCC 
setContent 
setSubject 
send 


OROEmailAdapter 





Figure 3: The class structure. 





e-mail class methods. (a) SMTPClient: 
(b) SMTPReply; (c) simple SMTPHeader. 
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done some programming work— the set 
and add methods collect information about 
the e-mail message. The send() method 
calls all of the ORO methods in the cor- 
rect order, feeding them the data that’s 
been previously collected. This is the first 
type of reuse that you'll see: simple code 
reuse. Every programmer normally would 
have had to do this kind of coding, some- 
where in their applications. The code I 
present here will eventually be accessible 
to everyone. The class definition class 
OROEmailAdapter implements EmailMes- 
sage is marked as implementing EmailMes- 
sage. This has two advantages: One, the 











Dr. Dobb’s Journal, February 1999 








compiler checks to make sure that the 
adapter really implements the interface — 
that it fulfills the specified contract. The sec- 
ond advantage will be clear as you read on. 

Also, notice how the class has the de- 
fault package visibility. It's not public like 
the interface. This means that application 
developers, or the programs they write, 
won't have access to it. They won’t be able 
to instantiate it. The Javadoc program by 
default won’t document it. Figure 3 shows 
the class structure to this point. 

The final step is to tie all this together 
by creating a public factory that hides the 
implementation class. 

The interface and the adapter are fin- 
ished. All that’s needed is a way to some- 
how give the outside world access to the 
adapter, yet not expose unnecessary de- 
tails. A “factory’— an object that instanti- 
ates other objects— is the solution. Mail. java 
(Listing Three) is a class that’s public. Its 
one method just returns a reference to an 
OROEmailAdapter. It can do that, because 
the factory is in the same package as the 
adapter. Note, though, that the reference 
is returned as type EmailMessage. Here is 
the second benefit of tagging the adapter 
as implementing the interface: The ORO 
adapter “is a” EmailMessage and can be re- 
turned as one from the factory. The actu- 
al adapter implementation class will be hid- 
den from users, who will only have an 
EmailMessage to work with. Figure 4 shows 
the factory structure. 

Factories are used extensively in frame- 
works that are intended to be adaptable 
and flexible. By hiding the instantiation 
of an object, clients are not dependent 
on implementation names. The San Fran- 
cisco project, for example, uses this idea 
extensively. (The SanFrancisco project is 
a reusable framework for building dis- 
tributed business applications in Java. It 
lets you write applications that are inde- 
pendent of data storage and other sub- 
systems; see. http://www.ibm.com/java/.) 

The client of these classes (that is, the 
customer) is the application programmer. 
Keeping the customer in mind will affect 
everything from method naming to docu- 
mentation. Everything done so far con- 
tributes to making the programmer’s job as 
easy as possible. For sending e-mail, a pro- 
grammer has the EmailMessage interface 
and the Mail class to rely on. This is all 
you need to do your work. Figure 5 shows 
this visually. MailTest.java (Listing Four) 
shows an example of how these classes 
are used. This is where the small extra ef- 
fort starts to pay off. Note how nothing 
about “ORO” appears in the code. Also, 
note how the code is clear and short, with- 
out any unnecessary details. Even if you 
are the only developer, you'll appreciate 
how your application-layer code becomes 
simpler with this design style. 
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Finally, notice that although as a de- 
signer, you must consider adapters, fac- 


New interfaces can 
apply to a whole 


category of 
subsystems 





tories, and patterns, an application pro- 
grammer doesn’t have to understand 
these underlying mechanisms. They just 





use the factory class in what becomes a 
natural way. 


Conclusion 

What the design by interface process 
does is create a horizontal interface be- 
tween two or more independent subsys- 
tems. This means that the new interface 
can apply to a whole category of (e-mail) 
subsystems, as opposed to only one im- 
plementation. It’s now much easier to 
make changes on either side of the in- 
terface, as well as move to different im- 
plementations. 

Real reuse and decoupling have been 
achieved — e-mail facilities can be used 
from many different applications with- 
out fear of becoming dependent on a 
single implementation or manufacturer. 
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The actual e-mail system being used could 
be swapped out at any time. 

I’m still investigating the payoffs of de- 
sign by interface, and exploring the differ- 
ent ways it can be used. In conclusion, here 


are some ideas for taking this approach 
even further. 


e Use Java’s reflection and dynamic bind- 
ing to allow adapters to be specified at 
run time. Its class name can be read 
from a properties file or command-line 
option. The factory class can make sure 
it implements the proper interface be- 
fore instantiating it. This can make your 
system configuration even more flexi- 
ble if necessary. For example, someone 
who purchased your system could con- 
figure it to use a new adapter without 
needing access to your source code. 

e Apply design by interface whenever 
there are multiple subsystems that 
must use each other’s services. Some 
examples could be a GUI, a datastore, 
or an authentication system. Objectspace 
(http://www.objectspace.com/) does 
this with its Voyager Db interface. 

e Use this design style for all of your Java 
packages. In his Java development 


guidelines (http://www.chimu.com/ 
publications/javaStandards/index.html), 
Mark Fussell suggests that you make the 
interfaces the only public items, and write 
at least one factory class per package that 
gives access to the implementations. 

e Apply interface-based design as a 
software-development process. This 
can lead to a plan where every devel- 
oper is productive, regardless of expe- 
rience level. Those with more experi- 
ence become system architects, defining 
interfaces and specifying services and 
behavior. Developers with less experi- 
ence are assigned the task of creating 
implementations of predefined inter- 
faces. With interface-based design, the 
emphasis shifts from the actual imple- 
mentation towards the interface. This 
means that it’s no longer important if 
the (novice) programmer’s code is too 
slow, or uses too much memory. As 
long as it conforms to the interface, it 
can be used. In the future the imple- 
mentations can be optimized or refined 
if they have to be. 
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Figure 5: The customer's relationship to the factory. 
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Listing One 


// file: EmailMessage. java 
package net; 
import java.io. IOException; 
/** A a simple email message class. It allows email messages to be sent 
* easily from Java. Here's how it is used: 
* <pre> 
* EmailMessage message = Mail.newMessage(); 
* message.setSender("santa@north. pole") ; 
* message.addRecipient ("shecter@lion-ag.de") ; 
* message.setSubject("Have you been naughty or nice?"); 
* message.setContent("Just checking..."); 
* message.send() ; 
* </pre> 
* The order of the various set()'s and add()'s is not important. Just 
* make send() the last operation. Multiple recipients can be specified by 
* calling addRecipient() or addCC() multiple times. 
* @see Mail 
* / 
public interface EmailMessage { 
/** Specify the <code>From:</code> header of the message. **/ 
public void setSender (String address) ; 


/** Specify a <code>To:</code> header of the message. This can be 
* invoked more than once for messages with multiple recipients. 
* / 

public void addRecipient (String address) ; 


/** Specify a <code>Cc:</code> header of the message. This can be 
* invoked more than once for messages with multiple recipients. **/ 
public void addCC(String address) ; 


/** Specify the <code>Subject:</code> header of the message. **/ 
public void setSubject(String subject) ; 


/** Specify the actual text of the message. **/ 
public void setContent (String content) ; 


/** Connect to the mail server and deliver the message. 
* @exception IOException can be thrown for many, many reasons. **/ 
public void send() throws IOException; 


Listing Two 


// file: OROEmailAdapter. java 
package net; 


import java.io.*; 
import java.util.*; 
import com.oroinc.net.smtp.*; 


/** An EmailMessage implementation that uses the ORO tcp/ip toolkit. **/ 
class OROEmailAdapter implements EmailMessage { 
private static final boolean DEBUG = false; 
private Vector recipients new Vector(); 
private Vector ccs new Vector(); 
private String subject bale 
private String content 
private String server 
private String sender 


we. 
, 


null; 


public OROEmailAdapter(String server) { 

this.server = server; 

} 

public void setSender(String address) { 

sender = address; 

} 

public void addRecipient (String address) { 

recipients .addElement (address) ; 

} 

public void addCC(String address) { 

ecs.addElement (address) ; 

} 

public void setSubject(String subject) { 

this.subject = subject; 

} 

public void setContent (String content) { 

this.content = content; 

} 

public void send() throws I0Exception { 

SMTPClient client = new SMTPClient(); 

client.connect (server) ; 

debug (client.getReplyString()) ; 

if (! SMTPReply.isPositiveCompletion(client.getReplyCode())) { 
throw new IOException("SMTP server refused connection") ; 

} 

client.login() ; 

debug (client. getReplyString()) ; 


SimpleSMTPHeader header = makeHeader (client) ; 
Writer writer = client.sendMessageData() ; 
debug (client. getReplyString()); 
if (writer == null) { 
throw new I0Exception("Could not send message data") ; 
} 
writer.write(header.toString()); 
writer.close(); 
if (! client.completePendingCommand()) { // failure 
throw new IOException("Could not complete pending command") ; 
} 
client. logout () ; 
debug (client. getReplyString()); 
client.disconnect () ; 
I 
/** Create the header for the message. **/ 
private SimpleSMTPHeader makeHeader(SMTPClient client) throws I0Exception { 
// Prepare the 'From' header. 
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String from = sender.toString(); 
if (from == null) { from = '""; }; 
client.setSender (from) ; 


// Prepare the 'To' header. 
int toCount = @; 
String to = ""; 
Enumeration addrs = recipients.elements() ; 
while (addrs.hasMoreElements()) { 
toCount++; 
if (toCount > 1) { 
to += m Mis 
} 
String addr = (String) addrs.nextElement () ; 
debug ("adding recipient: "+taddr) ; 
client .addRecipient (addr) ; 
debug (client. getReplyString()) ; 
to += addr; 
} 
// Now we can instantiate the header. 
SimpleSMTPHeader header = new SimpleSMTPHeader (from, to, subject) ; 


// Add in cc's, if any. 
Enumeration carbonCopies = ccs.elements() ; 
while (carbonCopies.hasMoreElements()) { 
String addr = (String) carbonCopies.nextElement () ; 
client.addRecipient (addr) ; 
debug (client. getReplyString()); 
header.addCC(addr) ; 
} 
return header; 
} 
/** Simple debuging output **/ 
private void debug(String s) { 
if (DEBUG) 
System.out.println("debug in OROEmailMessage: "ts) ; 
} 


Listing Three 


// file: Mail.java 
package net; 
/** E-mail system. Use this class to construct new e-mail messages. 


* <pre> 

* EmailMessage mesg = Mail.newMessage() ; 

* </pre> 

* See the documentation for EmailMessage for details on how to manipulate 
* and send it.<p> 

* @see EmailMessage 

*« / 


public class Mail { 
/** Create a new email message that uses the default LION SMTP server. **/ 
public static EmailMessage newMessage() { 
return new OROEmailAdapter ("mail.lion-ag.de") ; 


} 


Listing Four 


// file: MailTest.java 
package net; 
/** A short program that sends test e-mail messages. **/ 
public class MailTest { 
public static void main(String[] argv) { 
/* Check command line arguments */ 
if (argv.length != 2) { 
System.out.println("Usage: MailTest <from> <to>"); 
System. exit (9) ; 


} 
/* Create and send a test message */ 
try { 
EmailMessage mesg = Mail.newMessage() ; 
mesg.setSender( argv[@] ); 
mesg.addRecipient( argv[1] ); 
mesg.setSubject ("Hello from Java!"); 
mesg.setContent("Hi! \n\n This is a test message."); 
mesg.send() ; 
System.out.println("Message was successfully sent."); 
} 
catch (Exception e) { 
System.out.println("An exception occurred: " + e); 
System.exit (1); 
} 
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Adding power 
and flexibility 





S. Balamurugan 


perl provides an interface to Perl from 
Java. The Jperl interface was written 
in C++ using Perl APIs and integrated 
into Java using the Java Native Inter- 
face (JNI). The APIs in Jperl also make ac- 
cessing Perl from C++ simple, with a sin- 
gle overloaded function that masks 
argument ordering, stack manipulation, 
and data structure conversion. The pack- 
age — freely available (courtesy of Texas 
Instruments) at http://www.angelfire.com/ 
in/sbm, from Comprehensive Perl Archives 
Network (CPAN) at http://www.perl.com/ 
CPAN-local/authors/id/S/SB/SBALA/, and 
from DDJ (see “Resource Center,” page 
5)— includes source code, examples, doc- 
umentation, and precompiled libraries for 
Solaris. To compile your own libraries, you 
need to install JDK 1.1.4, g++ 2.7.x, Perl 
5.002 (or higher). 
More specifically, the modules include: 


e jperl.c, which contains the implementa- 
tion for the Perl access in C++. 

e jperl.h, which contains the function pro- 
totypes. 

e jp.c and jp.h, which provide the JNI. 

e jp.java, which defines the package for 
Perl access. 


Accessing Perl from Java 

Before accessing Perl, you must make sure 
the path to libperl.so is added to LD_LI- 
BRARY_PATH and jp.class to the CLASS- 


The author is a software design engineer 
working for the ASIC group of Texas In- 
struments, India. He can be contacted at 
sbm@india.ti.com. 
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perl: Accessing 
Perl from Java 


PATH. jp.class defines six public methods 
for calling Perl subroutines, two for turn- 
ing debug on/off in the native code, and 
a constructor (see Table 1). 

The constructor jp) takes the path to 
the Perl file as a string argument and ini- 
tializes the interpreter. Ideally, the Perl file 
should include all the subroutines that will 
be called from Java. Only one instance of 
the Perl interpreter can be alive at a time; 
trying to initialize more than one instance 
throws a RuntimeException. 


Additional Perl modules (other than 
those required by the Perl file supplied to 
the jp() constructor) can be included at 
run time using JPLLoadLibrary(). This 
method takes as an argument the path of 
the Perl package and adds it to the inter- 
preter within the existing namespace. 

The DebugOn() and DebugOff) meth- 
ods turn the debug flag on and off in the 
native code. When the debug flag is on, 
arguments are passed to Perl subroutines, 
values are returned, and status messages 
are displayed on stdout. Make sure you 
unbuffer the output in Perl so that mes- 
sages from Perl and debug messages from 
the native code appear in order. In Perl, 
you can do this with select((select(STD- 
OUT), $ | = DIO);. 





Perl subroutines or package methods 
can be called using one of Java’s PLCall 
methods. There are three methods, one 
for each type of data being returned from 
Perl. Package methods can be called by 
specifying package_name::method_name. 
All PLCall methods take an Object array 
as an argument and make this data avail- 
able as arguments to the Perl subroutine 
through the “@_” array in Perl. 

PLCallScalar() calls a Perl subroutine 
and returns a scalar value. PLCallArray() 
calls the subroutine and returns a Perl list 
as a String[]. PLCallHash(), calls the spec- 
ified subroutine and returns a Perl Hash 
array (or a list with even numbers of ele- 
ments) as Hashtable in Java. If an odd 
number of elements are returned from 
Perl, a RuntimeException is thrown. 

Perl scalars can be converted to Jnte- 
ger, Double, or String, although all val- 
ues returned from Perl are stored as 
String. Hash arrays from Perl are con- 
verted to Java Hashtables. Both key and 
value are stored as String, which can 
contain an empty string if nothing is re- 
turned from Perl. In case of error in con- 
version from Perl data structure to Java, 
the string will contain “(null)” as its val- 
ue. All strings are guaranteed to be de- 
fined. 

As previously mentioned, PLCall meth- 
ods take an Object array as arguments to 
be passed to Perl. Application can direct- 
ly pass Integer, Double, or String arrays 
as valid arguments. If the application must 
pass a Vector or a Hashtable, an Object 
array has to be explicitly created and the 
Hashtable or Vector made elements of the 
Object array; see Listings One and Two. 
One of the most powerful features of Jperl 
is its ability to evaluate Perl expressions 
on the fly. The JPLEval method enables 
this functionality. It takes a Perl expres- 
sion as an argument, evaluates it, and re- 
turns a String array of results; for exam- 
ple, String/] EvRet = perl. IPLEval("$a = 'This 
is a test'$b = reverse($a);' + "return 


($a, $b);");. 
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Listings Three and Four give the com- 
plete picture. In Listing Three, the test.pl 
program contains two subroutines — 
MyPerlFunc and TestFuncHash. The first 
prints the arguments passed and returns 
them. The second creates a Hash array 
and returns it. In Listing Four, example.java 
uses jp.class to access the subroutines in 
test.pl. Almost all of these methods throw 
kuntimeException and IllegalArgumentEx- 
ception. The try-catch block is used to catch 
these exceptions and display error mes- 
sages. Hashtable.toString() displays a string 
representation of the hashtable. 


Accessing Perl from C++ 

Table 2 lists Jperl’s function calls. The 
PLInit() function initializes the Perl in- 
terpreter. It takes the path to the Perl file 
as an argument. This Perl file would nor- 
mally include all the subroutines that you 
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intend to call. PELoadModule() lets you 
add additional Perl modules at run time. 
This function takes the full path of the 
modulename as an argument and loads 
it into the interpreter. After you have fin- 
ished using the Perl subroutines, call 
PLClose() to release the resources held 
by the interpreter. 

Perl subroutines can be called using 
the overloaded PLCall function. The first 
parameter is the variable in which to re- 
turn the data, the second parameter is 
the subroutine name to be called, and 
the third parameter defines the format 
of the arguments to be passed to Perl. 


All PLCall() functions take a variable 


number of arguments and pass them as 
arguments to the Perl subroutine in @_. 
The functions return the number of el- 
ements returned by the Perl subroutine 
or —1 on error. 





blic methods for calling Perl subroutines. 


The return values from the Perl subrou- 
tine can be int, double, String (char *), and 
arrays of int, double, or String. You should 
call the appropriate PLCall() based on the 
expected return type from Perl subrou- 
tines. If you are not sure of the return 
types, use PLCall(), which takes the String 
array as the return parameter. Hasharray 
from Perl should be received as an array 
of String, with alternate elements being 
key and values. 

Each of the variable numbers of argu- 
ments is converted to an appropriate Perl 
data structure based on the type specified 
in format. Valid formats are %d for int, %f 
for double, %s for char *, %D for an ar- 
ray of int, %F for an array of double, %S 
for an array of char *. When passing ar- 
rays, the first argument should be the 
length of the array followed by the actu- 
al array; see Listing Five. 

Perl expressions can be evaluated with 
the PLEval() function, which takes a Perl 
expression as input, evaluates it, and re- 
turns the results as an array of String. 

PLGeneric() is similar to PLCall(), ex- 
cept that it concatenates all the return val- 
ues from Perl separated by the passed de- 
limiter and returns a single string. For 
example, sub foo { return ("Hai", 1): }, when 
called with PLGeneric() with delimiter 
“**” returns a single string “Hai**1” in 
retval. 

The PLCall( functions, as well as PL- 
Eval() and PLGeneric( ), allocate the nec- 
essary memory for returning the values 
from Perl. It is up to the application us- 
ing these functions to free them. 


Accessing Perl from Applets 

Since you cannot add native code to ap- 
plets, one workaround is to create a 
plug-in that exports the necessary func- 
tionality. These methods can then be ac- 
cessed from other applets on the same 
document. You need to download Net- 
scape’s Plug-in SDK (http://home.netscape 
.com/comprod/development_partners/ 
plugin_api/ index.html), write your own 
plug-in on top of jperl.c, and export the 
needed functionality. 


Conclusion 

The Jperl package provides programmers 
with the functionality of CPAN modules 
without having to rewrite them in Java. 
You can refer to the perlembed, perlguts, 
and perlcall documentation at http:// 
www.perl.com/CPAN-local/doc/manual/ 
html/pod/perl.html if you want to extend 
the C++ interface of Jperl. Refer to JNI 
documentation at http://java.sun.com/ 
docs/books/tutorial/native1.1/index.html 
if you want to extend the Java interface. 


DDJ 
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Listing One 
// Passing String array as argument to Perl. 


// Intger and Double arrays can be passed similarly. 
String[] INP = new String[2]; 


//... 04 in DP 
perl.PLCallScalar("MyFunc", INP); // Ditto for PLCallArray & PLCallHash 


e ° 
Listing Two 
// Passing a Hashtable and Vector as arguments to Perl 
Object[] ARGS = new Object[2]; 
Vector V; 
Hashtable H; 


Ji voce TUL dn BS VY 


ARGS[@] = H; 
ARGS[1] = V; 
perl.PLCallScalar("MyFunc",ARGS); // Ditto for PLCallArray & PLCallHash 


Listing Three 


test.pl 
sub MyPerlFunc 
{ 
my($a,$b) = @_; 
print Sa,":",$b, "vn"; 
return @; 
} 
sub TestFuncHash 
{ 
my($a,$b) = @_; 
my(%ret) = ("A"=>$a,"B"=>Sb) ; 
return ret; 
} 


Listing Four 


example. java 
import java.util.Hashtable; 
import java.util.Stack; 
import jp; // The Jperl interface 
class main 
{ 
public static void main(String[] args) 
if 
String[] INP = new String[2]; 
INP[@] = "Datai"; 
INP [1] "Data2"; 
try { 
// The perl file that contains the subroutines 
jp perl = new jp("test.pl"); 


//Turn on Debug if necessary 
//per1.DebugOn; 


// Make a call and ignore the returned value! 
String t = perl.PLCallScalar("MyPerlFunc", INP) ; 


String[] EvRet = perl.IPLEval("$a = 'This is a test’; 
$b = reverse($a); return ($a,$b);"); 

// Display result of evaluation 
for(int i=@;i<EvRet.length;it+) 

{ 

System. out.print1n(EvRet [i] ); 

} 
// Call Hash 
Hashtable H = perl.PLCallHash("TestFuncHash", INP) ; 


// Output content of Hash 
System. out.println(H.toString()); 
) 
catch(IllegalArgumentException e) 
{ 
System.out.println("Error caught "+e. getMessage()); 


} _ : 
catch(RuntimeException e) en celal Tevall 
if : 

System.out.println("Error caught "+te.getMessage()) ; 


} 


Listing Five 


// Intialize 
PLInit ("/user/java/dev/test/mytest.p1") ; 


// Passing a double array to Perl and recieving an int 

int I; // Return value 

double DA[] = ( 8.10, 0.20 } ; // Arguments to the Perl sub 
LCall(I,"TestFuncAI","%F",2,DA); // Length is passed before the array 


// Passing an int, float and string to Perl and recieving a Hash array 
char *%§S; 
int ct = PLCall(S,"TestFunc","%d%f%s",33, (double) 100,"Hello World") ; 
for(int i=@0;i<ct;it+) 
{ 
printf("%s\n",S[i]); 
} 
// Evaluate a Perl expression 
et = PLEval(EvalRet,"$a = 'This is a Test'; @b = split(/\\st/,$a); 
return @b;"); 
// print results here .... 
// Free resources 
PLCose() ; 
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| Join the Rebol Alliance 


Michael Swaine 


n 1984, I promised readers that Dr. 
Dobb’s Journal would not summarily 
dump its CP/M coverage merely be- 
cause DOS was the dominant operat- 
ing system. CP/M is not dead at DDJ, I as- 
sured readers. This month’s column 
doesn’t contain any CP/M coverage, but 
it does have some of the flavor of that 
promise in that it examines some para- 
digms of the past that still have promise 
for the future. In doing so it honors a more 
recent promise to the Amiga faithful, of- 
fended by my glib dismissal of their plat- 
form a few months back. Amiga is defi- 
nitely not dead. In addition to a health 
report on Amiga, I take the pulse of DOS 
and HyperCard, and provide a perfectly 
serious (but not too serious) answer to 
the question “What do you do with an 
obsolete computer?” But this isn’t entire- 
ly a column in praise of venerable tech- 
nologies. “Rebol” (pronounced “rebel” as 
in “Rebel Without a Cause,” “The Rebel 
Alliance,” “Rebel, Rebel, your face is a 
mess”) is a brand-new programming lan- 
guage, born of one developer’s quest. 


The Jedi Master 

Carl Sassenrath has been on a quest for 
something like 20 years. It’s been rough- 
ly that long since he took his passion 
for—and degree in— computer lan- 
guages to Hewlett-Packard, where, in ad- 
dition to the work on operating systems 
that he was hired for, he got involved in 
a variety of language projects. HP was 
one of four test sites for a language de- 
veloped at Xerox PARC called Smalltalk, 
and there were Lisp machines available 
to use, and Sassenrath took advantage of 
the opportunities. He wrote a C compil- 


Michael is editor-at-large for DD]. He can 
be contacted at mswaine@swaine.com. 
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er for the IBM PC when it first came out, 
he developed a version of Forth, and he 
developed a system for remote proce- 
dure calls in Pascal for HP. From that last 
project, a fascination with the idea of pro- 
grams messaging one another stayed with 
him. From HP he moved on to Com- 
modore, where he wrote the multitask- 
ing operating system kernel for the Ami- 
ga, and also did some language work. 
Then there was a stint at Apple, devel- 
oping one of the next-generation operat- 
ing systems that Apple couldn't get out 


the door. He used Smalltalk heavily there.. 


Following that, he wrote a LOGO inter- 
preter for Commodore. In the early ’90s, 
through his company, Pantaray, he was 
involved with set-top boxes, CD-ROM- 
based computers, programming languages, 
content authoring systems, and digital 
video tools. All the while he kept looking 
for the right language. Lisp held some fas- 
cination, but to Sassenrath it wasn’t real- 
ly the answer. Then, a few years ago, he 
decided to quit searching and just write 
the language he dreamed of. Messaging 
would be a key part of it; in fact, it would 
be the heart of the language. He got fund- 
ing, hired talented help, and dug in. When 
he came up for air last summer, the result 
of his efforts was Rebol. 


Send coruscant@galaxy.org 

“Hello world!” 

Last September, Sassenrath released the 
first incarnation of his vision, Rebol/Core. 
This product is and, Sassenrath assures us, 
always will be, free. That was part of the 
vision. 

Another part of the vision was porta- 
bility of code. The (interpreted) Rebol pro- 
grams run on any platform on which Re- 
bol runs, and Sassenrath has promised to 
put it on any platform for which he gets 





a serious request. That may be a hard 
promise to keep, but it does run on quite 
a variety of platforms already: Amiga; 
FreeBSD; Linux for Red Hat, Debian, and 
Slackware; Macintosh PPC; Solaris 2.6 
SPARC; and Windows 95/98/NT. Because 
he wants it to run identically on all plat- 
forms, he hasn’t opened up the source. 

Another part of the vision was mes- 
saging. “What’s programming about?” 
Sassenrath asks. “Messaging.” So although 
the language has affinities to Lisp and to 
Forth, is functional as opposed to proce- 
dural, and has some object orientation, 
the way he characterizes it is as a network 
messaging language. Interestingly, the mes- 
sages sent between programs are all text 
strings, as human readable as messages 
between program and person or between 
person and person. That makes the code 
easier to maintain, Sassenrath figures, sort 
of like cars used to be user-maintainable 
before their parts were electronic. That’s 
part of the vision, too. 

Some of the ideas for the language came 
from Sassenrath’s study of linguistics, and 
the Chomsky hierarchy, according to 
which (Sassenrath says) Rebol is context 
sensitive rather than context independent. 
“You need to separate the name space 
from the value space,” he says, and if you 
do, you end up with a language that is so 
malleable that people can mold it into the 
language they want. That, too, was part 
of the vision. You mold Rebol by creating 
a dialect, a specialized grammar for the 
language that serves your purposes. 

If you do a really exhaustive count, you 
find that there are thousands of pro- 
gramming languages, because people 
write languages to solve all kinds of par- 
ticular problems. Better they should de- 
rive a dialect of Rebol, Sassenrath thinks, 
and he has written the language with this 
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in mind. And Rebol has built-in Internet 
features. It knows about the main pro- 
tocols. Sending a file to an e-mail ad- 
dress is a one-liner in Rebol. The Rebol 
web site is maintained by a Rebol pro- 
gram, which you can download from the 
site (http://www.rebol.com/). You can 
also download Rebol/Core there for any 
of the supported platforms; the average 
size is about 250 KB. Other features: in- 
heritance, polymorphism, the ability to 
write functions for writing functions, ex- 
ception handling, and concurrency. 
Wherever you are in the code, if you or 
the kernel triggers an exception, the state 
will be saved. 

[Editor's Note: You can hear more about 
the Rebol vision in Philippe Lourier’s DDJ 
TechnetCast interview with Carl Sassen- 
rath at bttp:/Avww.technetcast.com/] 


So what does it look like? Listing One 
shows how to create a switch function in 
Rebol, and how to use it with Rebol’s data 


types. 
The Amiga Empire Strikes Back 


One of the platforms Rebol runs on is, 
not surprisingly, the Amiga. The Amiga 
computer is not even a little bit dead. One 
estimate of the installed base of Amiga 
users is 100,000. Amiga is still popular in 
Hollywood, for example, it was used in 
the production of the movies Jurassic 
Park and Titanic, and it’s used on Baby- 
lon V to animate all external views of the 
space ships. It’s still popular among sci- 
entists and engineers; an evolving net- 
work of Amigas has been in use by NASA 
at Cape Canaveral since 1987, and is like- 
ly to continue in use there for several 


Paradigms Past: 


more years. There’s a steady stream of 
new or updated software coming out for 
the platform, including Linux and Rebol. 
Other languages include assembler, C, 
C++, Pascal, Modula 2, Oberon, Fortran, 
Basic, BCPL, E, scheme, Cluster, ARexx, 
Lisp, and Prolog. 

The Amiga 1000, as you may or may 
not recall, was introduced in 1985. It was 
a multitasking, multimedia machine Cits lit- 
tle sister, the Commodore CDTV, was the 
first CD-ROM Multimedia device for home 
or school use). The first Amiga OS fea- 
tured preemptive multitasking, 32-bit struc- 
ture, and a color GUI. 

Commodore made a few errors, shall 
we say, leading to a bankruptcy sale in 
1995 in the Bahamas, where Escom AG, 
a German firm, bought the Amiga assets 
and formed Amiga Technologies. Hopes 


Collecting Old Computers for Fun and Profit 


or a shrewd investment. It can also be 

hard to justify to friends, relatives, and 
the other people sharing your living quar- 
ters. Classic cars, okay. At least they don’t 
clutter up the living room. Coins, stamps, 
seashells: These seem harmless fixations. 
But collecting beer coasters (tegestology)? 
I am reliably informed that the proper 
term for the collecting of Camembert 
cheese labels is tyrosemiophily. 

Oh, well. I won't pretend to under- 
stand why some people collect the things 
they collect, but I think I understand 
some of the motives for collecting in gen- 
eral. Emotional attachment to the thing 
collected. Respect for the art or craft that 
went into producing it. Pleasure in us- 
ing it (which might help to explain col- 
lecting classic cars, but not canceled 
stamps). Investment potential. The urge 
to preserve disappearing artifacts. An at- 
tempt to recapture one’s youth (I’m think- 
ing of comic books and baseball cards). 

Around those artifacts that people 
collect seriously — classic cars, stamps, 
and so forth—a rich culture grows up. 
There are clubs, regional conferences, 
shows, museums, publications, formal 
methods of evaluating finds, and a his- 
tory or folklore. So far, that hasn’t hap- 
pened with computers. Although many 
people collect computers, for many of 
the reasons listed earlier, computer col- 
lecting has not yet become an orga- 
nized hobby in the sense that coin col- 
lecting or stamp collecting has. But it’s 
about to. 


(ras can be an expensive hobby 
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Kevin Stumpf's self-published book A 
Guide to Collecting Computers and Com- 
puter Collectibles: History, Practice, and 
Techniques (1998; ISBN 0-9684244-0-6) 
comes at a perfect time. Kevin, a long-time 
computer collector, has thought long and 
hard about the needs of collectors, and 
has produced a book that could single- 
handedly launch the collecting of vintage 
computer hardware as a serious (but not 
too serious) hobby. Say you’ve decided to 
start collecting all the Data General hard- 
ware you can lay your hands on. Outside 
of dumpster diving on Route 128, where 
do you look? Kevin has a lot of ideas about 
sourcing, listing two dozen different types 
of sources and various techniques for scor- 
ing the stuff once you sniff it out. 

One indication that collecting comput- 
ers is not yet a serious hobby is that there 
is no set of agreed-upon guidelines for ap- 
praising the collectible worth of old com- 
puters. Kevin doesn’t go so far as to pro- 
duce a Blue Book pricing guide, but he 
does something more appropriate to the 
current state of collecting: He outlines cri- 
teria and methods for evaluating old hard- 
ware in terms of its authenticity, rarity, sig- 
nificance, and condition, and presents 
examples to show how to use these crite- 
ria. A VIC-20 would be a common micro, 
for example, an IMSAI 8080 an uncommon 
one, and an Apple I a rare one. 

The chapters on acquiring, cataloging, 
storing, restoring, and repairing deal with 
important questions that you might not 
think of early in your collecting experi- 
ence. How do you establish ownership if 


you acquire the thing through barter or as 
a gift? How do you transport a mainframe 
computer, and what do you do with it 
once you get it home? What information 
about your acquisition should you record 
in your collection catalog? What are the 
temperature and humidity limits for stor- 
ing magnetic tape? How do you remove 
crayon marks from old paper? Kevin has 
also begun the process of documenting a. 
folklore of computer collecting. The anec- 
dotes and profiles of collectors that he 
sprinkles throughout this book nicely cap- 
ture the spirit of collecting and the fasci- 
nation that old computer hardware holds 
for many of us. I defy any Dr. Dobb’s read- 
er to thumb through Kevin’s book and not 
be reminded of their first PDP-8 or TRS- 
80 Model I or IBM 360/22 or whatever it 
was. This book won't tell you how to get 
rich from the junk in your garage, but it 
will open your eyes to a rewarding and 
fascinating hobby, and give you all the 
knowledge you need to get started in com- 
putophily. This book is a first edition, ring- 
bound and self-published. It badly needs 
an editor to fix the typos and grammati- 
cal errors and inconsistencies and to rein 
Kevin in when his anecdotes gallop off 
the trail. But the depth of knowledge and 
the scope of coverage more than offset 
the book’s flaws. I hope that there are 
many future editions (and that those edi- 
tions have the benefit of professional edit- 
ing). For now, I’m tickled that I have a first 
edition of a book that I think could be- 
come a minor classic. oe 
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soared, hopes fell. Escom itself declared 
bankruptcy in 1996. 

Meanwhile, though, the Amiga users 
and developers kept the dream alive, and 
in 1997, Gateway acquired the assets of 
Amiga Technologies and formed two cor- 
porations, Amiga Inc. in the U.S. for de- 
velopment and Amiga Technologies 
GmbH in Germany to handle marketing. 
The current flagship of the line is the 
Amiga 4000T with a 68040 or 68060 pro- 
cessor, but Gateway’s plans include new 
hardware and new OS kernel. Last 
November, it was announced that QNX 
would provide the real-time OS kernel 
for the next version of the Amiga OS. 
The hardware is still unannounced as I 
write this, but don’t expect the next Ami- 
ga to use a PowerPC or Pentium chip. 
And although the new Amiga will be a 
radical redesign, it will probably run ex- 
isting (well-behaved) applications, so as 
not to disappoint those 100,000 fans. 

And as long as I’m posting nondeath 
notices, here are a couple of signs of the 
continuing health of DOS: Ithree Micro 
Technology (http://www.ithree.se/) claims 
to have the first true 32-bit DOS and the 
first true 32-bit BIOS. And xChaos Soft- 
ware distributes the Arachne web brows- 
er for DOS 5.0, which will run on an 8086 
machine with as little as 425 KB RAM. In- 
tegrated e-mail, PPP dialer. Free at http:// 
hotfiles.zdnet.com/cgi-bin/texis/swlib/ 
hotfiles/info.html?fcode=000Q41. 


Never Tell Me the Odds 

I don’t have any official word on the 
health of HyperCard—I suspect that there 
is no official word as I write this— but 
the signs are not good. Little development 
seems to have been done recently toward 
the long-delayed release 3.0, programmers 
have reportedly been pulled off the pro- 
ject in favor of others, and rumors are that 
Steve is not crazy about it. 





Listing One 


REBOL [ 
Title: "Switch Function" 
Date: 15-Oct-1998 
File ‘%switch.r 
Author: "Carl Sassenrath" 
Purpose: { 
Switch between a set of choices or a default. 
Should make C programmers happy. 
} 
] 


switch: func [value cases /default case] [ 


"Select from a set of choices. Return the evaluated case." 


value: select cases value 
if found? value [do value] 
else [if default [do case] else [none] ] 
] 
Examples: { 
Print "Switch can be used in many ways:" 
;-- Works for simple numbers: 
switch 22 [ 
11 [print "here"] 
22 [print "there"] 


} 
switch/default 400 [ 
11 [print "here"] 
22 [print "there"] 
] [ print "nowhere"] 
;-- Or, words used as symbols: 
car: pick [Ford Chevy Dodge] random 3 
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Too bad, because thousands of edu- 
cators are crazy about it, hundreds of use- 
ful, entertaining, and educational prod- 
ucts were built with it, and Apple appears 
to have nothing in the wings to bring on 
in its place. Although the current version 
is, frankly, an embarrassment, with its 
tacked-on support for color and other ’80s 
flashback features, it is still a powerful 


Some of the ideas 
for Rebol came from 
Sassenrath’s study 
of linguistics 


power-user-level development system 
with no equal on any other platform, and 
the reason many people stay with the 
Mac, especially in Apple’s maintain- mar- 
ket-share-or-die education market. So I 
find it hard to believe that Apple will drop 
HyperCard, even though it seems clear 
that this is exactly what they are in the 
process of doing. Quietly. So ’m making 
some noise about it. If Apple does drop 
HyperCard, that wouldn’t have to mean 
that it’s dead. First, because several prod- 
ucts have some degree of HyperCard 
compatibility and might be able to step 
into the breach. 


print switch car [ 


Ford [ 351 
Dodge [ 154 


;-- Strings too: 
html-tag: "pre" 


print switch html-tag [ 


* 1.4 ] 
Chevy [ 454 * 5.3 ] 
* 3,5°] 





SuperCard began its life as a HyperCard 
clone and still has much in common with 
HyperCard. Although SuperCard has had 
its ups and downs as well, it is alive to- 
day and could easily profit from Apple’s 
dropping HyperCard. SuperCard is not as 
easy to get to know as HyperCard and has 
evolved away from it in many ways, but 
it seems plausible that it could capture 
most of the stackheads out there with a 
little careful repositioning, compatibility 
tweaking, and a few other strategic 
changes. MetaCard is now available for 
the Mac as well as UNIX and DOS/Win- 
dows. It’s Scott Raney’s HyperCard clone, 
which he’s been working on for years. 
Again, it’s a different user experience, but 
an easy transition for HyperCard users. 

LiveStage had some early buzz that sug- 
gested that it might be a HyperCard re- 
placement. The developers, Totally Hip 
Software, quickly distanced themselves 
from that hype. The product, a front end 
for QuickTime, is interesting enough with- 
out the hype. But it is not beyond the 
realm of possibility that it could become 
a HyperCard replacement. If Apple dumps 
HyperCard, Totally Hip should think about 
it. What all these products need in order 
to capture the HyperCard audience (“mar- 
ket” isn’t the word) is the ability to import 
almost all existing HyperCard stacks and 
run them with little or no modification. 
Some technical help from Apple could 
make that a lot easier for them. Better yet, 
Apple could just release the source code. 
Given that the primary user pool for Hy- 
perCard is students and teachers, that 
would seem to be a particularly good idea, 
if Apple isn’t going to advance the prod- 
uct itself. In fact, I insist. Steve, let us have 
version 3.0 or let us have the source. 

There, that oughta do it. 


DDJ 


"HREF" ["Hypertext Reference"] 


" IMG" 
" PRE" 


["JPEG or GIF Image File"] 
["Preformatted text"] 


"LI" ["Bulleted list item"] 


] 


;-- Times (dates, or most other types of values in REBOL): 


time: 10:30 


switch/default time [ 


8:00 [send wendy@domain.dom "Hey, get up"] 
12:30 [send cindy@dom.dom "Join me for lunch."] 
16:00 [send group@every.dom "Dinner anyone?"] 

] [print "Nothing to do!"] 
;-- The "cases" can be a variable too: 


schedule: [ 
8:00 


16:00 
] 


switch time schedule 


do Examples 


[send wendy@domain.dom "Hey, get up"] 
12:30 [send cindy@dom.dom "Join me for lunch."] 
[send group@every.dom "Dinner anyone?"] 


DDJ 
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C PROGRAMMING 


The Envelope, Please 


Al Stevens 


n my December 1998 column, I chal- 

lenged readers to remember the origins 

of the name D-Flat as a “C Program- 

ming” column project, inaugurated in 
April, 1991, and continuing for about two 
years. D-Flat was an MS-DOS text-mode 
applications framework implemented first 
as a C function library and later wrapped 
in a C++ wrapper. The first reader with 
the correct answer would be acknowl- 
edged in this column. The results are in, 
and reader Bob Sundling is the winner. 
Bob wrote: 


All I can remember offhand is that you had 
hoped to call D-Flat “C-Sharp” but were 
worried about infringing on someone’s 
trademark. Maybe since it’s written in C and 
looks “sharp”? 

Bob’s answer is close enough to earn 
him the coveted prize of mention in this 
august venue and an official DDJ T-shirt. 
Several readers whose entries came in lat- 
er had researched their back issues or 
made a fast query of the DD] CD-ROM to 
find my introduction to the project and 
explanation of the name, as follows: 


Because all the really good C-oriented puns 
have already been taken (C-Worthy, C- 
scape, and so on), I will call the package 
“D-Flat,” which is another way of saying 
“C-Sharp.”...I will not use “C-Sharp” itself 
because there is almost certain to be some- 
one out there with a trademark registration 
and a lawyer on the payroll. 


I am happy that readers keep back is- 
sues and use the DD/ CD-ROM, but I am 
nonetheless gratified that the winning en- 
try comes from someone whose memory 
served up the answer. When readers re- 
member such details, it tends to attach a 
measure of endurance to work that I did 
so long ago. (Not that I have to worry 
about leaving a lasting legacy. Y2K and 
all those Cobol programs I wrote in the 
60s and ’70s are certain to preserve my 
place in history.) 

Ian Ashdown gets honorable mention 
for being the only reader in lo these 
many years to identify a product named 


Al is a DDJ contributing editor. He can be 
contacted at astevens@ddj.com. 


Dr. Dobb’s Journal, February 1999 


“CSharp,” thus justifying my original con- 
cerns and validate my conservative nam- 
ing practices. He reports that he reviewed 
the CSharp Realtime Toolkit in the June 
1985 issue of Computer Language maga- 
zine almost six years before I was con- 
sidering and rejecting the same name for 
my project. 

To complete the meaning for those of 
you who are not musically inclined, C 
Sharp and D-Flat are the same note on 
the piano. 


Testing Quincy 99 

Quincy 99 is the latest version of a Win32- 
hosted GUI IDE front-end for gnu C/C++ 
compilers. Quincy 99’s primary purpose 
is to serve as the development platform 
for D-Flat 2000. I introduced Quincy 99 
and D-Flat 2000 in December. 

The original Win32 versions of Quincy 
(96 and 97) used a beta version of the 
gnu-win32 port of the gnu compilers. 
Sometime between that version and the 
egcs-1.1 mingw32 version that I am using 
now, the format changed for the debug- 
ging information generated by the com- 
pilers. The compilers insert debugging 
statements, called “stabs,” as macros into 
the assembly-language files they gener- 
ate. The assembler translates those state- 
ments into tables in the object files that 
describe each source code symbol and 
line number in the program. The changes 
to the stabs format were not drastic, but 
they were significant enough that I had to 
redo much of the code that processes 
stabs. As a part of that exercise, 1 substi- 
tuted STL containers for the tables that 
Quincy’s debugger uses to associate Mmein- 
ory addresses with statement line num- 
bers, symbols with addresses, and so on. 

Quincies 96 and 97 are not without 
bugs, but they work well enough to sup- 
port the exercises in the C/C++ tutorial 
book and CD-ROM for which they were 
originally intended. After rewriting the 
stabs processing code for Quincy 99, 1 val- 
idated the program with the suite of ex- 
ercise programs from the book. At that 
point, I was tempted to declare victory 
and use Quincy 99 as it was. That would 





have been a mistake. Remembering my 
larger purpose for Quincy 99— to be the 
development environment for D-Flat 
2000-—1 decided that the IDE needed a 
rnore comprehensive test than I could pro- 
vide alone. None of my exercises were 
GUI applications, for example, so a ma- 


jor part of Quincy 99 was untried to any 


extent whatsoever. Thus a formal Quincy 
99 beta test began. 

Readers around the world are testing 
Quincy 99 as I write this column. I posted 
the Quincy 99 source code and binaries on 
my web site (http://www.midifitz.com/al- 
stevens/quincy99/) and encouraged read- 

rs to download and test it. I recruited the 
first round of testers from an announce- 
ment that I posted on a mail list dedicat- 
ed to the Cygnus ports of the gnu com- 
pilers. Reports from those testers have 
revealed bugs that my own testing did not. 
Some testers have suggested changes to 
improve Quincy 99. Others have explained 
how I might deal with problems that Quin- 
cy has endured since its 96 version. 


Quincy and NI 

One such problem was that Quincy did 
j0t work properly under Windows NT. 
That had always been a thorn in my side. 
NT users complained that Quincy would 


‘not report compile errors. There was no 


indication that a compile did not process 
to successful completion, yet the compil- 
er generated no executable file. I responded 
to many such complaints by explaining that 
Quincy is a Windows 95 application and 
i0t validated under NT, which, I am sure, 
caused many readers to gnash their dis- 
gruntled teeth. Quincy launches the gnu 
compiler tools— the preprocessor, com- 
piler, assembler, linker, and librarian— from 
within the IDE. Quincy uses the Win32 C7e- 
ateProcess function for that launch, which 
permits the launched process to inherit file 
handles. Quincy is a Win32 GUI applica- 
tion, so it has no console device. The com- 
piler tools are Win32 console applications, 
and they write their error messages to the 
stderr device. Quincy creates a text file and 
tells the compiler tools that the file handle 
represents the standard error device. The 
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presence of error messages in the text file 
following a program build indicates to 
Quincy whether the compile is successful. 
Although this procedure worked flawless- 
ly with Windows 95, no error messages 
were ever posted to the file under NT. 

One of the fallouts of the beta test was 
the solution to this problem with NT. I 
posted the problem in the README file 
in the list of unsolved problems, and a 
tester responded. Bruce Wampler is the 
author of the “V C++ GUI Frameword” 
(http://www.objectcentral.com/). He had 
similar problems with VIDE, the integrat- 
ed development environment he is devel- 
oping with V. He told me about his solu- 
tion and, between us, we got Quincy to 
properly direct the compiler tool error 
messages to a file under NT. 

Having done that, I announced that 
Quincy now supported NT, only to hear 
from another tester, Roger Frank, who re- 
ported that the NT computers at the high 
school where he teaches programming 
had another problem with Quincy. You 
could compile any program as many times 
as you wanted and you could debug any 
program as many times as you wanted, 
but not both. Once you debugged the pro- 
gram, the compiler refused to rebuild the 
executable file. Quincy’s debugger had 
the exe file locked for write access until 
you exited and restarted Quincy. This 
problem, too, occurred only under NT, 
and it was a puzzler. Quincy 97 did not 
exhibit this behavior, although 97 and 99 
use the same protocols for launching de- 
bugged programs and compiler tools. The 
difference was found in the nature of the 
executables that the two IDEs launch. 
Quincy 97 launches programs compiled 
to use cygwin.dll, which implements a 
POSIX translation layer under Win32, and 
Quincy 99 launches programs compiled 
to use the Win32 API directly. 

To the rescue came another tester. Ja- 
cob Navia is the author of the LCC-Win32 
compiler system (http://www.cs.vir- 
ginia.edu/~lcc-win32/) from which I ex- 
tracted the resource compiler and editor 
to integrate with Quincy 99. Jacob had en- 
countered similar problems with his de- 
bugger and gave me enough information 
to find the solution. When a program uses 
CreateProcess to launch another program 
in debug mode under NT, the launching 
program needs to close the launched pro- 
gram’s File handle when the debug ses- 
sion is finished. It is still a mystery why 
Quincy 97 does not exhibit the same be- 
havior. I can only speculate that some- 
thing in the POSIX layer of the launched 
programs defeats the file lock. 

By the way, there is a new version of 
Quincy 97 available for readers of Teach 
Yourself C++, Fifth Edition and the A/ 
Stevens Cram Course on C/C++ CD-ROM. 


112 


The new version works with NT. You can 
download it by going to http://www.mid- 
ifitz.com/alstevens/quincy97/. 

Conducting a test program such as 
Quincy 99’s is a fairly straightforward pro- 
cess. I post each new build on the web 
site. Anyone who wants to be notified of 
the new builds sends e-mail to me saying 
so. I announce each new build in an e- 
mail message to those people on the list. 
If someone stumbles across the software, 
downloads it, and sends me a comment 
or a bug report, I add them to the list. 
Anyone who no longer wants to be an- 
noyed by unwanted build announcements 
(I update the builds as often as necessary, 
sometimes daily) can ask to be taken off 
the list. This is really low-tech stuff, so I 
don’t suggest that you duplicate these pro- 
cedures to beta test a big system with a 
large body of testers. 


Where Is D-Flat 2000? 

Over the past few weeks, most of my ef- 
fort has been directed at making Quincy 
99 work well enough to be the develop- 
ment platform for D-Flat 2000, my ambi- 
tious project to build a Win32 application 
framework that uses Standard C++ fea- 
tures such as templates, exceptions, con- 
tainers, and namespaces in the imple- 
mentation. As a result, not even the 
simplest version of D-Flat 2000 is ready 
to be published. Not that I am neglecting 
the task. I have already started to write 
code. But that task uncovered a serious 
deficiency in my knowledge. 

That deficiency is the product of my stub- 
born nature. I steadfastly refused to learn 
Windows programming in the days when 
all a programmer had was the Windows C 
API. I would not consider doing so until 
mature C++ compilers and framework class 
libraries were available, which, of course, 
eventually came to be. As a result, my 
knowledge of the Win32 API extends most- 
ly to those things that MFC does not sup- 
port. Fortunately, MFC does not try to raise 
everything to higher levels of abstraction, 
and an MFC programmer needs a rudi- 
mentary understanding of such things as de- 
vice contexts, fonts, command messages, 
and so on. I say fortunately because other- 
wise I’d have a lot more to learn about the 
underlying API that I am attempting to wrap. 

This all came home to me when I start- 
ed to design the D-Flat 2000 window class, 
the top-level class in a windows hierar- 
chy that supports document views, but- 
tons, and so on. Virtually everything vis- 
ible in a GUI application is a window. I 
called on my experience writing the orig- 
inal D-Flat and set about to design a win- 
dow class that would encapsulate the be- 
havior that all windows have in common. 
Whereupon I stopped dead. D-Flat had 
to do it all. There was nothing underneath 


except some hardware and BIOS. D-Flat 
2000 has (spoken in the vaporware tense) 
Win32 at its foundation. To know what to 
wrap and what to implement, I need to 
know what the foundation already does. 
I already knew that the API supports dis- 
playing windows based on window class- 
es (in the pre-C++ API vernacular; not C++ 
classes) that the programmer provides. But 
I found myself adding a data structure to 
support the relationship between parent 
and child windows, and it occurred to me 
that the API probably already does that. 
So here I am, several years later, learning 
what I vowed never to learn— how to 
program a Windows application in C so 
that I know what the API provides and 
what I have to provide. One step forward, 
two back. 


From the D-Flat 

2000 Design Notebook 

The following paragraphs come from my 
design notes. I provide them here so that 
you can ride along with me on the winds 
of whim. Please react as critically as you 
wish to anything you see here. This is the 
beginning of the project, and you have 
the opportunity to influence the outcome. 
Flame away. 

D-Flat 2000 does not revolutionize the 
user interface paradigm. Applications look 
to the user like traditional Windows ap- 
plications with documents and views, 
menus and dialogs, and so on. 

D-Flat 2000 takes a different view of 
the application from the programmer’s 
perspective. Abstractions can be ex- 
pressed with templates. Conceptually, a 
D-Flat 2000 application is a bag that con- 
tains an application window, menus, tool- 
bars, dialogs, documents, and so on. Un- 
like STL containers, wherein each 
instantiation contains only objects of a 
single type, a bag instantiation can con- 
tain different kinds of objects. No such 
container is implemented in Standard 
C++ unless you consider an STL bag to 
be a standard container that contains 
pointers to different kinds of objects de- 
rived from a common base class. Stan- 
dard C++’s run-time type information 
supports such a concept by allowing the 
program to determine at run time the 
type of an object retrieved through a ref- 
erence taken from the container. 

Goal: Wrap only the user interface and 
leave the rest to the Win32 API. Eventu- 
ally add other APIs (multimedia, telepho- 
ny, serial communications, and so on) as 
needed and as time permits. 

Encapsulate the view paradigm with- 
in the document paradigm. MFC does a 
marginal job associating documents and 
their views, and the code idioms for get- 
ting a view from a document are cum- 
bersome. 
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Find a better paradigm for capturing 
command messages. An MFC programmer 
is not always sure whether a particular 
menu/toolbar command message should 
be processed by the view class, the doc- 
ument class, the application class, or the 
frame window class. 

Why should the application class and 
its frame window be separated, other than 
to differentiate between document-based 
and dialog-based applications? DF Wrap, 
the C++ wrapper around the original C 
D-Flat library, integrates an application and 
its window. Why not use inheritance to 
implement the two different application 
behaviors? 

Goal: Find an alternative to Hungarian 
notation. 


Hungarian Notation 

I never really liked Hungarian notation, 
an identifier naming convention that en- 
codes identifiers with a prefix that spec- 
ifies the type of the object associated 
with the identifier. You can read about 
Hungarian notation at http://ivory.lm.com/ 
~gregleg/hungarian.html. I have used 
subsets and supersets of it because some- 
thing told me I should be conforming to 
Windows programming conventions 
when I write a Windows program, and 
MFC uses it extensively, applying a 
superset to accommodate the C++ lan- 
guage. (One MFC extension is the use 
of the m_ prefix to differentiate between 
data members and other variables in 
member functions.) 

To not use Hungarian notation in an 
MFC program is to have a hodgepodge 
of identifers with no apparent conven- 
tion of conformity. How important is 
that? I don’t know. Others are passion- 
ate about naming conventions and I am 
not, but the D-Flat 2000 project provides 
an opportunity to use something other 
than Hungarian notation. The C++ 
namespace feature will surely influence 
whatever convention, if any, falls out of 
this project. And if namespaces have any 
redeeming quality at all, it is that they 
might contribute to a viable alternative 
to what Ray Duncan calls “the Hungar- 
ian gibberish.” 

Years ago at a programmer’s conven- 
tion, I was on a C++ panel that includ- 
ed Bjarne Stroustrup, P.J. Plauger, Jim 
Coplien, and other C++ luminaries. A 
programmer from the audience asked for 
the panel’s opinion about what he 
should do when his management insist- 
ed on mandating coding conventions such 
as Hungarian notation. Dr. Stroustrup’s 
quick response was, “Could you find an- 
other job?” 


DDJ 
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C++ source code. 
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JAVA Q&A 


How Do | 





Store a Java App in a 
Self-Executing Encrypted File? 


Dave Angel and Andy Wilson 


very nontrivial Java application re- 

quires multiple class files, but dealing 

with them can be a pain. One prob- 

lem with multiple class files, for in- 
stance, involves installation. Installation of 
any software, not just a Java application, 
often requires registry keys and sometimes 
additional environment variables. Java ap- 
plications are especially prone to class- 
path issues, and sometimes even class 
packaging incompatibilities, such as those 
between zip and cab files. 

A second problem with multiple class 
files is that Java makes it all too easy for 
users to decompile and reuse an applica- 
tion’s classes. Each class you create takes 
some measure of time and money. How- 
ever, typical Java packaging methodologies 
allow others to steal your work. 

One way to get around both problems 
is to create zip files. However, zip files of- 
ten require users to modify the classpath. 
Secondly, zip files are not encrypted, so 
users can unzip files and decompile or use 
your classes. 

The only real solution to both prob- 
lems, therefore, is to build a custom en- 
cryption and packaging system and im- 
plement it as a_ self-extracting, 
Java-executable file. Even though the de- 
fault Java class loader looks to the class- 
path to find a given class file, a class can 
override the default loader and control 
how and where additional classes are 
found and loaded. This lets you create any 
packaging method you wish. In this arti- 
cle, we'll present CodePacker (available 
electronically; see “Resource Center,” page 
5), a custom loader that is both easy to 
install (it’s self-extracting) and secure. 


Dave and Andy are software developers 
at NuMega Lab-Compuware. They can be 
contacted at davea@numega.com and 
andyw@numega.com, respectively. 
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Class File Format 

This project consists of two distinct parts, 
the codepacker executable and a template 
file called container.class. The codepacker 
executable takes a list of all the user de- 
fined classes, and combines them with the 
container.class into a single, self-extracting 
executable class file. 

For example, “Java codepacker con- 
tainer.class username.class depend1.class 
depend2.class main.class” would produce 
a single class file called “username.class.” 
This class file (username.class), when ex- 
ecuted, would load and run the user's 
main class, which is the last one listed 
(main.class). Naturally, username.class 
would also load the dependent classes, 
shown here as depend1.class and de- 
pend2.class. A Java class file is a specific 
format defined for the portability of ob- 
ject code from one implementation of a 
virtual machine (VM) to another. 

A class file consists of a number of fields 
and counted arrays, most of them con- 
taining variable length items. The main 
portions are the constant pool, interface 
list, field list, method list, and attribute list. 
Additionally, there’s the “this” index, a 
fixed-size field between the constant pool 
and interface list. 

The constant pool, like all the lists, starts 
with a count. Then it has a number of 
items, each starting with a 1-byte tag. De- 
pending on the type, the data in that con- 
stant pool item may be of fixed size, or it 
may have a byte count itself. The partic- 
ular items we’re interested in here are of 
the CONSTANT_Utf8 type, which consists 
of counted UTF8 strings. UTF8 encoding 
is a way of representing Unicode such that 
ASCII characters only take up one byte 
each, while nonASCII values may take 
one, two, or three bytes. 

Throughout the rest of the file, when an 
index is used, it usually refers to a particu- 





lar item in the constant pool. Especially in 
the case of strings, this avoids repetitious 
usage of the same thing throughout the file, 
and makes much of the rest of the data a 
fixed size. 

The first index we use is the “this” in- 
dex, which simply describes the name of 
the class file with which you’re dealing. 
Since you can let users rename the Con- 
tainer class, you have to change the string 
that the index points to or change the in- 
dex to point to another string. 

There are several predefined attributes 
that describe the Java class. For example, 
one attribute is Code, which contains the 
byte code and a few other fields. The VM 
will only process attributes that it recog- 
nizes. Consequently, you can add a new 
attribute and not affect the behavior of the 
application. 

Being able to manipulate the class-file 
format is critical to the notion of a self- 
extracting class file. The next step is to 
execute a contained class’s main method. 


Invoking Main 
The Java reflection classes let you load, 
query, and invoke class methods. Using the 
reflection classes, container classes are able 
to detect which classes have a main method. 
However, detecting which class has a 
main method isn’t enough. A Java appli- 
cation may have several classes that have 
main methods. Often these extra main 
methods contain unit-testing code. Con- 
sequently, there needs to be an addition- 
al way for the user to specify the main 
executable class for the self-executing 
class. The application can do this by ei- 
ther having a command line option or re- 
quiring the user to order the list of class- 
es in such a way that the main class is 
distinct from supporting classes. 
Invoking the main class is rather trivial. 
The application must first query the class 
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via the java.lang.Class.getDeclared- 
Method() method to find the main 
method. This method takes two param- 
eters, a string representing the method, 
and an array of parameters. To find the 
main method, the application would call 
getDeclaredMethod() with a string of 
“main” and an array containing a String 
array. 

Once you have found the main method, 
you simply invoke it. The getDeclared- 
Method() returns a java.lang.reflect 
Method object. From the main of the self- 
executing class, we call the Method.in- 
voke() method with the String array us- 
ing the same parameters passed to us from 
the command line. Control then passes to 
the encrypted executable class’s main() 
method. 
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the inside scoop on Windows N 


Dr. Dobb's Systems Internals 


Packaging Classes 

Packaging a list of class files into a data 
file is trivial. However, what if the class 
list's data was partially encrypted? What 
if various sections of the class list used 
different encryption methods? Now the 
problem of how to handle this data be- 
comes much more complex. 

Before answering these questions, we 
need to set a few ground rules. First, as- 
sume the user will specify a list of class files; 
however, that list will include class files that 
encrypt and decrypt data. Second, the ap- 
plication will not use incremental encryp- 
tion. Instead, the application switches from 
one encryption method to another. Third, 
only class-file data is encrypted. Fourth, the 
main class file has some special attributes 
to distinguish it from other class files. 
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These rules define the structure 


int type; 
int length; 
byte[] encrypted_class_file; 


that will represent a single class file. 
The type field tells how to handle the class 
record. This value indicates if the class is 
the main class, an encryption/decryption 
class, or just a typical support class. The 
length field represents the length of the 
encrypted_class_file field. The bytes of 
the encrypted_class_file field hold an en- 
crypted class file. An array of these struc- 
tures represents a list of encrypted class- 
es. This tells how we are going to take a 
list and convert it into a list of encrypted 
classes; the second problem is where to 
put them. There are several ways to load 
a class into a VM. We will choose a way 
that current decompilers will not support. 

You can create a new attribute con- 
taining the encrypted class file list and 
write the data to some other class file. The 
VM will simply ignore the class list data 
and execute the class file as usual. How- 
ever, the application can read its own class 
file, decode the class file list, and load the 
resulting classes directly into the VM. 


CodePacker Example 

CodePacker is a Java application that en- 
crypts a list of class files into another class. 
Users specify an ordered list of class files 
to encrypt, and a target name for the re- 
sulting class file. 

The entire application is dependent on 
only three class files. The CodePacker.class 
file is responsible for loading, encrypting, 
and writing a list of class files to an at- 
tribute in another class. 

The second class, Container.class, is the 
base class for all encryption/decryption class- 
es and extends the ClassLoader abstract class. 
This class first exposes two static methods, 
encrypt) and decrypt). These methods are 
null place holders. By extending from the 
ClassLoader class, the Container class is able 
to load classes into the VM. The Contain- 
er.class file is also responsible for the de- 
coding and loading of stored class files, and 
invoking the main class file. 

The third class is the encryption/decryp- 
tion class file, derived from Container. The 
Container class’s encrypt and decrypt meth- 
ods do nothing. Consequently, it is neces- 
sary to override the Container class en- 
crypt/decrypt method for the application to 
use an encryption method. 

The application is broken down into four 
phases: packaging, encryption/decryption, 
loading, and execution. 


Packaging. The class packaging 
method is the method this application 
uses. The application simply builds a 
ByteArrayOutputStream object and 
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(continued from page 116) 

writes the class bundle to the list (see 
Listing One). As the application works 
through the class list, it is able to switch 
between encryption methods by exam- 
ining the class file list and searching for 
methods with a signature matching the 
Container class’s encrypt() method. 

Once the array of class data is built, the 
application writes the data to the target 
class file in 48 KB blocks. An attribute may 
be as large as 64 KB, however, this gives 
the application a little more leeway should 
the encrypted class structure require ad- 
ditional fields. 

After the class array is written to the 
Container class, an additional attribute is 
added to the end of the attribute table. 
This added attribute specifies the begin- 


-lLint 


{ 

int value; 

public: 

X(); 

xX( char * ); 

X( const char * ); 
operator char *(); 
3 


int main() 
{ 
xX xX; 
delete x; 
return 0; 


} 


ning index of the attribute table for the 
class file. This will simplify loading by al- 
lowing the application to simply read the 
last few bytes of the class file and move 
to the offset it specifies. This is much faster 
than reading the entire class file and in- 
terpreting each element of every table. 
However, many other modifications also 
occur. First, attributes require a string con- 
stant in the constant pool. This string must 
uniquely identify the attribute so that the 
VM can distinguish custom attributes from 
those the VM should try to interpret. An- 
other important change is that the user is 
able to specify a target class name. This 
means that the name of the Container 
class must be a changeable option. This 
will require the CodePacker to add a new 
entry to the constant pool specifying the 
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new name, and update the “this” field to 
point to the new name index. 

The safest way to perform all of these 
steps without destroying the original file 
is to read in the entire class and rewrite 
it with all of its changes and additions. 

Encryption/Decryption. Once you 
are unpacking the class files, you can also 
decrypt them. The interface to the en- 
cryption and decryption methods is sim- 
ple enough that you can substitute more 
complex algorithms of your choosing. 
Each method takes a byte array, and re- 
turns a (different) byte array. The only re- 
quirement is that the decryption method 
be able to invert whatever the encryption 
method does. 

Looking at Listing Two (Encrypt.java), 
we see a single class with two methods. 
It would have been better to break it into 
two separate classes, but it’s simpler to 
describe this way. The principle used is 
that one can easily find a pair of 32-bit 
integers that are inverses of each other, 
assuming normal twos-complement over- 
flow. In other words, when you multiply 
them together, the result will equal 
Ox00000001. It also turns out, with sim- 
ple algebra, that if you multiply any oth- 
er value by one of them, then by the oth- 
er, you wind up with the original number. 
In other words, if we call these inverses 
magicl and magic2, then (X*magic1) * 
magic2 == X for all possible values of X. 

Next, we introduce a random 24-bit 
seed (extracted just before starting en- 
crypt, and stored in an int). For each 
byte of the buffer, we merge the byte 
with the seed (to get a 32-bit value), 
multiply by magic, then extract one byte 
from the result, saving the other three 
in seed. Repeat for all the bytes of the 
buffer, and then add three more bytes 
of seed to the end of the buffer. At this 
point, the buffer has grown by 3 bytes, 
and contains all the information from 
the original buffer, plus the information 
of the randomly chosen seed. Of course, 
this information is nicely scrambled by 
the magic of our multiply scheme. 

Much later, when the loader invokes 
our decrypt method, we reverse the pro- 
cess. Using the inverse magic value, we 
start by extracting the final seed value 
from the last three bytes of the buffer. 
Then we work backwards through the 
buffer, applying the same algorithm (but 
with the inverse magic value). When 
we're done, we have the original seed 
value (which we discard), and the pre- 
cise buffer we started with. The buffer 
is returned to the caller, who hands it to 
the VM as a class file image. 

We now know everything necessary 
to store a list of class files. 

Loading. To execute the contained 
application, users merely run the target 
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Container class. The class begins by 
opening its own class file as an ordinary 
data file. It begins by going to the last 
few bytes. This portion of the class file 
indicates the location of the first class 
data attribute. The application can then 
seek that location and read in all the 
class data. 

Once all the data is read in, the appli- 
cation rebuilds the data array and inter- 
prets the data. The data is a mix of en- 
crypted data. However, it follows the 
format where the first integer specifies the 
type of class. The second integer speci- 
fies the length of the data. The third inte- 
ger specifies the size of the encrypted data. 


The application calls the decryption rou- 
tine, and loads the resulting class image 
into the VM. 

Executing. The last step is to execute 
the main class file. Once all the classes 
are loaded into the VM, the application 
invokes the contained application’s main 
method, passing the command line pa- 
rameters from the Container class. The 
contained application will execute and be- 
have as though it were loaded by the nor- 
mal VM’s class loader. 


Conclusion 

CodePacker demonstrates that it is possi- 
ble to build a self-extracting, encrypted 
Java application. By using a combination 


of encryption and class file manipulation, 
it is possible to create a single class file 
that contains all the component classes of 
an application. 

The next step would be to add fea- 
tures to manage the intelligent loading 
of system-dependent libraries, resources 
(bitmaps, icons, and so on), and class 
files that are specifically geared to a giv- 
en platform. As a side benefit, it is also 
possible to use a Container class file as 
a package library, giving the package 
some protection from those who de- 
compile your work. 


DDJ 





Listing One 


public void build ( ) 
if 


} 


byte[] encryptedClasses = readClassFiles( ); 
writeClassFile( m_destination, m_newName, encryptedClasses ); 


protected byte[] readClassFiles( ) 
{ 


CodePackerClassLoader cl = new CodePackerClassLoader () ; 
ByteArrayOutputStream bout = new ByteArrayOutputStream() ; 
DataOutputStream out = new DataOutputStream( bout ); 


for 


| 


} 


( int i = 0; i < m_pFiles.length; it+ ) 


try 
{ 

Method c = null; 

byte[] classBytes = cl.readClassFile ( m_pFiles[i], true ); 

c = cl.getEncrypt( stripExtension ( m_pFiles[i] ) ); 

if ( m_crypto != null ) 

{ 
System.out.println ( "Encrypting something " + 

classBytes.length ); 
classBytes = (byte[])m_crypto.invoke( null, 
new Object[] { classBytes } ); 
System.out.println ( "Encrypted something " + 
classBytes.length ); 

} 

if (c != null ) 

{ 
System.out.println ( "Switching cryptography method" ); 
m_crypto = c; // switch to new crypto class 
out.writeByte( 1); // crypto class 

} else if ( i == ( m_pFiles.length - 1) ) 


// is this the last file in the list 
// main class is always last class in list 
out.writeByte( 2 ); 

} else 


out.writeByte( @ ); // do nothing special with the class 
} 
out.writeInt( classBytes.length) ; 
out.write( classBytes ) 
} catch ( Exception e ) 
{ 
System.out.println ( e.getMessage() + " occured in build " ); 


} 


return bout.toByteArray() ; 


protected String stripExtension( String className ) 


if ( className.endsWith( ".class" ) == true ) 
{ 


return className.substring(@, className.length() - 
".class".length() ); 


} 
return className; 
} 
public void writeClassFile ( String name, String newName, byte[] bytes ) 
try 
{ 
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RandomAccessFile inFile = new RandomAccessFile( name,"r" ); 
RandomAccessFile outFile = new RandomAccessFile( newName, "rw" ); 
// write magic number, major and minor version info 

int magic = inFile.readInt(); 

int minor = inFile.readUnsignedShort () ; 

int major = inFile.readUnsignedShort(); 


outFile.writeInt( magic ); 
outFile.writeShort( minor ); 
outFile.writeShort( major ); 


// write the attribute table 
int constCount = inFile.readUnsignedShort () ; 
outFile.writeShort( constCount + 2 ); 


int codePackerAttributeIndex = constCount; 


long[] offsetTable = new long[ codePackerAttributeIndex ] ; 
short j = @; 

for ( j=0; j < (constCount-1); j++ ) 

{ 


int type = inFile.readUnsignedByte() ; 
outFile.writeByte( type ); 


switch ( type ) 
{ 


case 1:// utf-8 
int len = inFile.readUnsignedShort() ; 
byte[] utf8bytes = new byte[len]; 
inFile.read ( utf8bytes ); 
//System.out.printin ( (j+1) + " UTF8 "+ 

new String(utf8bytes) ); 

outFile.writeShort( len ); 
outFile.write( utf8bytes ); 
break; 

case 3: // int 

case 4: // float; 
outFile.writeInt (inFile.readInt()); 
break; 

case 5: // long 

case 6: // double 
outFile.writeLong(inFile.readLong()); 
{tt 
break; 

case 7: // class 

case 8: // string 
if ( type == 7 ) 
{ 


int tmp = inFile.readShort(); 
//System.out.println ( (j+1) + 
" Class utf8 at index " + tmp ); 
offsetTable[ jt+1 ] = outFile.getFilePointer(); 
outFile.writeShort ( tmp ); 
} else 
{ 
outFile.writeShort (inFile.readShort()); 
J 
break; 
case 9: // field 
case 10: // method 
case 11: // interface 
case 12: // name and type 
outFile.writeInt (inFile.readInt()); 
break; 
default: 
System.out.print ( "Unknown type" ); 
break; 
} 
} 
// write a new UTF8 object for the new class name 
int classNameIndex = jt+1; 
outFile.writeByte( (byte) 1 ); 
String tmpName = stripExtension ( newName ) ; 
outFile.writeShort( tmpName.getBytes().length ); 
outFile.write( tmpName.getBytes() ); 


// write the type, length and new attribute info 

int customAttributeIndex = j+2; 

outFile.writeByte( (byte) 1 ); 

outFile.writeShort( "CodePackerCustomAttribute". 
getBytes().length ); 

outFile.write( "CodePackerCustomAttribute".getBytes() ) 


/* Attribute table is now written */ 
// write access flags 
outFile.writeShort( inFile.readUnsignedShort() ); // access Flags 


// replace this index with classConstIndex to represent new name 
int thisIndex = inFile.readUnsignedShort(); // this index 
outFile.writeShort( thisIndex ); 

long currentPosition = outFile.getFilePointer (); 


outFile.seek( offsetTable[ thisIndex ] ); 
outFile.writeShort ( classNameIndex ); 
outFile.seek ( currentPosition ); 


// write the super class 
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outFile.writeShort( inFile.readUnsignedShort() ); 


// write the interface table 

int interface_count = inFile.readUnsignedShort () ; 

byte[] interfaceBuffer = new byte[ interface_count * 2 ]; 
inFile.read( interfaceBuffer ) ; 


outFile.writeShort( interface_count ); 
outFile.write ( interfaceBuffer ); 


// write the field table 
writeFieldMethodTable( inFile, outFile ); 


// write the method table 
writeFieldMethodTable( inFile, outFile ); 


// write attribute table 
long attributesOffset = outFile.getFilePointer () ; 


System.out.println ( "Attribute Offset at " + attributesOffset ); 


int attributes_count = inFile.readUnsignedShort () ; 
outFile.writeShort ( attributes_count ); 


// write exisiting attributes 
for ( int k = @; k ¢ attributes_count; kt+ ) 


writeAttributes( inFile, outFile ); 


// write class data attributes 

int attributesAdded = writeAttributeRecords( outFile, 
customAttributeIndex, bytes ); 

// write attribute to indicate start of attribute table 

outFile.writeShort ( customAttributeIndex ); 

outFile.writeInt ( 9 ); 

outFile.writeByte ( (byte) 1 ); 

outFile.writeLong ( attributesOffset ); 

attributesAddedtt; 


// set the attribute count with the new attributes 
outFile.seek ( attributesOffset ); 
outFile.writeShort( attributes_count + attributesAdded ); 
System.out.println ( "attributes: "+ ( attributes_count + 
attributesAdded ) ); 
} catch ( Exception e ) 


e.printStackTrace() ; 
} } 
Listing Two 


import java.util.*; 
public class Encrypt extends Container 
if 
public static int seed; //note, it's really three bytes 
public static int magic; 
public static byte scrabble(byte value) 
{ 
int temp = seed | (value<<24); 
temp *= magic; 
seed = temp & Oxffffff; 
temp >>>= 24; 
return (byte)temp; 
} 
public static byte[] encrypt(byte[] bytes) 
{ 
System.out.println ( "Encrypt.encrypt() " + bytes.length ); 
//Given an array of bytes, produce another array of bytes, 
// somewhat longer, that are an encoding of that array 
int size = bytes.length; 
byte[] buffer = new byte[size+3] ; 
seed = (int) (16000000.*java.lang.Math. random()) ; 
magic = 653216881; 
for (int i=@; i<size; ++i) 


buffer[i] = scrabble(bytes[i]); 


(byte) (seed>>16) ; 
= (byte) (seed>>8) ; 
a 


byte) seed; 


buffer[size] = 
buffer [sizet1] 
buffer [size+2] 
return buffer; 
} 
public static byte[] decrypt(byte[] bytes) 
{ 


//Given an encoded array of bytes, produce another array of bytes, 
// somewhat shorter, that are the original set 
magic = 1278932113; 
int size = bytes.length-3; 
byte[] buffer = new bytel[size] ; 
seed = bytes[size] &255; 
seed = (seed<<8) | (bytes[sizet1]&255); 
seed = (seed<<8) | (bytes[size+2]&255) ; 
for (int i=size-1; i>=@; --i) 
buffer[i] = scrabble(bytes[i]); 


return buffer; 


DDJ 
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uppose you are the president of a 

major airline. Your fleet of commuter 

jets is showing its age and you have 

a mandate from the board to pur- 
chase 20 new aircraft. Some of the factors 
you may take into account are reliability, 
fuel consumption, maintenance costs, price 
of spare parts, and pilot preference. In 
turn, each of these factors may require 
weighing a large number of individual 
data points. 

The total number of factors can easily 
run into the hundreds or thousands (es- 
pecially where acquisition of military 
equipment is concerned, or where tax- 
payer money is concerned). Naturally, 
some factors are more important than oth- 
ers, but it’s by no means clear how to com- 
bine them all together to give an answer. 
To add to this difficulty, some inputs may 
be unquantifiable, or only specified in 
vague terms. 

In this article, I present the analytic hier- 
archy process (AHP), a decision-making 
tool for exactly this type of problem. De- 
vised by Thomas Saaty of the Wharton Busi- 
ness School (see Mathematical Methods of 
Operational Research, by T.L. Saaty, Dover, 
1988), it’s a simple but intriguing analytical 
technique for reducing complex decisions 
to a series of comparisons and rankings. 
The results are then combined to give a sin- 
gle, unequivocal result. 


Andrew writes financial and medical soft- 


ware in Sydney, Australia. You can reach 
him at amcolin@aol.com. 
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I'll illustrate how the process works by 
using the AHP to select one of several 
compilers for use in an introductory C++ 
course. The aim is to select the compiler 
that has the best match to student needs, 
based on an assessment of the relative im- 
portance of the features available in a C++ 
package, and the competing strengths of 
three rival products. 

The first step in using the AHP is to 
make a list of the factors to be considered 
in the decision. For a student compiler, 
factors such as cost, quality of the docu- 
mentation, and whether or not the com- 
piler supports exception handling are im- 
portant. The ability to produce fast run 
times or handle legacy code is less of a 
priority. The AHP then requires you to 
construct a hierarchy of factors that will 
lead up to your decision. 


Divide and Conquer 
A hierarchy lets you move from general 
questions and preferences (How impor- 
tant is the quality of development envi- 
ronment?) to the more specific (How im- 
portant are run-time sizes?) to the 
particular (How good is the loop unrolling 
algorithm?). Grouping documentation pref- 
erences or C++ specifics is natural. This 
lets you state broad preferences, such as 
“cost is more important than a slick envi- 
ronment,” or “cost is only slightly more 
important than standard C++ constructs.” 
Figure 1 shows the hierarchy tree I’ve 
designed for this problem. The form of 
the tree is fairly straightforward to for- 





it pee Fie-system d de- 


at Kientzle : 


mulate in this case, but may require con- 
siderable thought for more complex cas- 
es. This is a point at which it may be 
useful to brainstorm with colleagues. 

The next step is to decide on the rela- 
tive importance of each factor at each lev- 
el. For instance, Table 1 assigns purely 
subjective numbers to the level-1 features. 
With these numbers, you can construct a 
matrix of pairwise comparisons, showing 
the relative importance of one criterion 
over another (Table 2). 

Next, you form a set of weightings for 
the four features, so that: 


e Higher weightings are given to features 
with a higher score. 

e The scores add up to 1 (this is impor- 
tant, because you will later be using this 
technique over a range of different vari- 
ables and levels). 


To derive a set of weights from this 
matrix that you can use for subsequent 
decision making, you need a little math- 
ematics. A proof demonstrated by Saaty 
shows that the optimal set of scores is 
the principal eigenvector of this matrix. 
The proof requires knowledge of the 
kernels of linear transformations. Al- 
though the general eigenvector problem 
can be complex, there are several algo- 
rithms to calculate principal eigenvec- 
tors in a simple iterative manner, one of 
which I have implemented in Listing 
One. For this matrix, the eigenvector is 
{0.3, 0.2, 0.4, 0.1}, which forms the set 
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Figure 1: A hierarchy for selecting a C++ development environment. 


of weights showing the relative impor- 
tance of each feature. 

Once you have a set of weights for these 
four features, it’s a straightforward matter 
to rank the competing products. For each 
compiler, simply multiply the weight of each 
feature by a score showing how well the 
compiler implements that given feature. The 
sum of these scaled scores is the compil- 
er’s overall score. The compiler with the 
highest score is the winner. 





You may be wondering why you don’t 
simply add up the relative preferences 
and normalize to 1. After all, this would 
be much simpler and gives the same an- 
swer. The reason is that the way users 
feel about product (or feature) A, com- 
pared to product (or feature) B, may not 
precisely reflect how they feel about B 
compared to A. Neither score is wrong; 
it’s just that an imprecise value judgment 
is being made. 

In this case, the pairwise comparison 
matrix may not be consistent, so that off- 
diagonal elements may not be the re- 
ciprocal of their transpose entries. This 
could be a problem if you were restricted 
to normalizing vectors, since you would 
then be unable to produce the weights 
by simple normalization. However, the 
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Table 3: One way to assign numerical values to subjective comparisons. 
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eigenvector formulation handles such 
cases with ease. The resulting vector sim- 
ply reflects a composite view of the two 
conflicting judgments. This is a major 
strength of the AHP, in that it combines 
imprecise, vaguely specified, and even 
contradictory preferences into a single, 
unequivocal result. 


Quantifying Vague Preferences 
Suppose you can't easily supply a nu- 
merical score for a set of attributes. Saaty 
suggests that you construct a matrix where 
each off-diagonal element is acquired by 
comparing the two factors in importance 
using a scale like that in Table 3. For in- 
stance, if A is strongly more important 
than B, then A is 5 times as important as 
B, while B is 1/5 as important as A. 

You can use this scale if it’s just too dif- 
ficult to numerically rank a group of fea- 
tures. Suppose you were called on to rank 
famous composers— who would be rash 
enough to say, “Mozart is 2.334 times bet- 
ter than Puccini.” And would this mean 
that Puccini is 0.4285 as good as Mozart? 
Rather than making silly numerical pro- 
nouncements of this form, you would be 
better advised to use a verbal scale of the 
aforementioned form. The power of the 
AHP in this type of case is that it will still 
give useful answers, even with the in- 
evitable inconsistencies that will creep in 
due to the lower precision. 

But what happens when you want to 
actually compare different products 
against each other to provide scores for 
each product? The answer is that you can 
use exactly the same approach. Instead 
of comparing the importance of features, 
we rank how well the product imple- 
ments that feature. For instance, on Cost, 
the three compilers are ranked as (80 per- 
cent, 50 percent, 20 percent) showing that 
the first compiler had the highest score, 
presumably because it was cheapest. This 
means that the relative scores for the 
three products are (0.533,0.333,0.133). 
The contribution from Cost to the first 
compiler’s final score is therefore 0.533 
(the first compiler’s score for Cost) times 
0.3 (the importance that Cost has in the 
final reckoning). 

As mentioned, it may happen that you 
can’t agree on absolute scores for the 
products. In this case, you can carry out 
a pairwise comparison of the appropriate 
features, comparing one against the oth- 
er. For instance, “ease of use of IDE” is 
going to be particularly hard to judge 
numerically, and it makes more sense 
here to compare each of the rival prod- 
ucts with each other. 

Since the algorithm is recursive, you can 
build hierarchies of features. I’ve illustrated 
this by making the decision on “C++ fea- 
tures” dependent on two subfeatures: 
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whether the compiler supplies the Stan- 
dard Template Library (STL), and 
whether it supports exception handling. 

After deciding that having the STL avail- 
able is twice as important as supporting 
exception handling, the weights for these 
two features are therefore (0.667, 0.333). 
Applying a score of 9 if the compiler sup- 
ports the given feature and 1 if it doesn't, 
we come up with the scores (0.052, 0.474, 
0.474) for STL support and (0.474, 0.474, 
0.052) for exception handling. The over- 
all compiler scores for C++ features are 
therefore (0.192, 0.474, 0.333), and these 
scores are fed back to the higher levels 
for the final decision. 

Listing One implements the AHP in C. 
The hierarchy for the problem is set up 
as an n-ary null-terminated tree. Levels in 
the hierarchy are set up as elements in a 
statically declared array, where each ele- 
ment contains the following: 


e Number of subcases. 

e Names of the attributes. 

e Pairwise comparison matrix. 

e Addresses of the elements that form the 
subhierarchy. 


I’ve assigned the scores in Table 4 to 
each of the three fictional compiler’s fea- 
tures. Matrices of pairwise comparisons 
have been written into the static array at 
the head of the program. 

The matrix for the top-level decision 
has deliberately been made inconsistent. 
The importance of cost compared to doc- 
umentation has been given as 3/2 above 
the diagonal, and as 2/1 below the di- 
agonal. The matrix values are found in 
Table 5. 

Since the calculation of principal 
eigenvectors is so quick, I have made 
no effort to distinguish between cases 
where we can calculate a priority vec- 
tor from simple normalization, and cas- 
es where we actually need the eigen- 
vector machinery. 

When the program is run, eigenvectors 
are calculated for each element in the hi- 
erarchy and each case is evaluated recur- 
sively to give a final score. The winning 
compiler in this case was the ByteMan- 
gler with a score of 0.439. Although not 
the first choice on cost, it had a better de- 
velopment environment and documenta- 
tion than the competition. The Nanosoft 
and Outprise compilers came in second 
and third with scores of 0.288 and 0.272, 
respectively. 

A natural extension to this idea would 
be “what-if” sampling. Assuming you 
start with top-level weights and work 
downward in level of detail, there may 
occur cases where varying the values of 
some low-level attributes makes no dif- 
ference at all to the final answer. The 
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Table 4: Rankings for three fictional development environments. 
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Table 5: Matrix for top-level decision. 


values of these unimportant inputs on them. Knowledge of such inputs 
would then be ignored and no further (which could be found using sensitivity 
effort would be expended in working analysis or Monte Carlo techniques) 
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could result in saving substantial time 
and resources. 

References to commercial tools that 
implement the AHP can be found at 
http://expertchoice.com/, which has 


more information, and downloads of 
commercial demos. There is a dazzling 
array of ingenious uses of the technique, 
ranging from selecting mutual funds and 
choosing boat hulls for the U.S. Coast 


Guard, to predicting (correctly, as it 
turned out) Saddam Hussein’s moves in 
the Gulf War. 


DDJ 





Listing One 


/* FILE: ahp.c 

** AUTHOR: Andrew Colin 

*k DATE: 29th October 1998 

** DISCLAIMER: No liability is assumed by the author for any use made 
** of this program. 

**k DISTRIBUTION: Any use may be made of this program, as long as the 
** clear acknowledgment is made to the author in code and runtime 

*k executables. The author retains copyright. 


* / 


#include <stdio.h> 
#include <stdlib.h> 
#include <math.h> 
#include <time.h> 
#include <assert.h> 


#define MAX_ATTRIBUTES 10 
#define N_CASES 3 
#define MAX_ITERATIONS 100 


#define randomize() srand( (unsigned) time (NULL) ) 


typedef struct element { 
int n_factors; /* Number of attributes/items */ 
char attributes [MAX_ATTRIBUTES] [OxFF]; /* Not used */ 
double preferences [MAX_ATTRIBUTES] [MAX_ATTRIBUTES]; /* rankings */ 
struct element *branch[MAX_ATTRIBUTES]; /* Address of sub-attribute */ 
double eigenvector [MAX_ATTRIBUTES]; /* computed rankings */ 
double ranking[N_CASES]; /* Final, relative worth of each choice */ 
} ELEMENT; 


ELEMENT array[] = { 
{ 4 ; {"Top-level" ; MH : Wott P wd") A 
14151.5,0.75,3):;,.667,1,0.5.2) .{1.333.,.2:4 43 {0 333:,0.5,0.25,1}}, 


{&array[1], &array[2], S&array[3], &array[4])} }, 


3,{"Documentation"},{{1,0.25,0.333},{4,1,1.333},{3,0.75,1}}, {NULL}}, 
3, {("Cost"}, ({1,1.6,4},(0.625,1,2.5},(@.25,8.4,1}}, { NULL } }, 

3, {("IDE"}, ({1,0.714,1.25},(1.4,1,1.75},{@.8,0.571,1}}, { NULL } }, 

2, ("C++ features"}, ({1,2},{@.5,1}}, ( G&array[5], &array[6] } }, 

3, ("STL library"}, ({1,0.111,0.111},(9,1,1},(9,1,1}}, € NULL } }, 

3, ("Exception handling"}, {{1,1,9},(1,1,9},{@.111,0.111,1}}, {NULL}}, 


(aon ill oon till aon tl aon til aon lan) 


/* Multiplies a matrix m and a vector v; returns the result in vector 
* r. Note the syntax for passing a statically declared multidimensional array 
* to a function (see K&R, pi12, second edition) 
*/ 
void mmult( int size, double m[] [MAX_ATTRIBUTES], double v[], double r[] ) { 
ant dy 13 
for (i=@; i<size; itt) { 
r[{i] = 0.0; 
for (j=0; j<size; j++) 
r[i] += m[i] lj] * v[jl; 


/* Given a matrix m, this routine returns the normalized principal 
* eigenvector e using the power method (see Burden and Faires, 
* Numerical Analysis, Prindle, Weber & Schmidt, 1985, pp 452-456) 
*/ 
void np_eigenvalue( int size, double m[MAX_ATTRIBUTES] [MAX_ATTRIBUTES] , 
double e[MAX_ATTRIBUTES] ) { 
double v[MAX_ATTRIBUTES] ; 
double largest, s, sum; 
int i, iteration; 
/* Initial random guess for eigenvector */ 
for (i=0; i<size; it+) 
v[i] = (double)rand() / RAND_MAX; 
iteration = Q; 
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while (iteration < MAX_ITERATIONS) { 
/* Construct new approximation to eigenvector */ 
mmult( size, m, v, e ); 
/* Find largest element in new eigenvector */ 
largest = 0.0; 
for (i=@; i<size; it+) { 
s = fabs(e[i]); 
if (s > largest) 


largest = s; 
} 
/* Normalise by dividing by element of largest absolute magnitude */ 
for (i=@; i<size; i++) 


e[i] /= largest; 
/* Copy new approximation to old approximation */ 
for (i=@; i<size; i++) 

v[i] = efi); 
++iteration; 


} 

/* Normalise eigenvector so that sum of elements 

sum = 0.0; 

for (i=@; i<size; 
sum += e[i]; 

for (i=@; i<size; 
e[i] /= sum; 


1 */ 


itt) 


itt) 


/* Evaluates the priority vector for each node in the decision 
* tree. This routine calculates the principal eigenvector of the 
* array 'preferences' and writes it to the array ‘eigenvector’. 
*/ 
void get_eigenvector (ELEMENT *e) { 


np_eigenvalue( e->n_factors, e->preferences, e->eigenvector }s 


/* Recursive routine to evaluate the ranking vector for an element of 
* a hierarchy, where the priorities (or principal eigenvectors) have 
* already been calculated. 

*/ 
void evaluate_hierarchy( ELEMENT *e ) { 

int. 45. 33 

if (e->branch[@] == NULL) { /* At bottom level of hierarchy */ 
assert (e->n_factors == N_CASES) ; 
for (i=@; i<N_CASES; i++) 

e->ranking[i] = e->eigenvector [i] ; 
} 
else { 

for (i=0; /* At intermediate level */ 


i<e->n_factors; i++) 


_ garni 


"DDK At AHE 





evaluate_hierarchy( e->branch[i] ); 
for (j=0; j<N_CASES; j++) ( 
e->ranking[j] = 0.9; 
for (i=@; i<e->n_factors; it+) 
e->ranking[j] += e->eigenvector [i] 
* e->branch[i] ->ranking[j] ; 


} 
} 
#ifdef _DEBUG 
for (i=@; i<N_CASES; itt) 
printf("Ranking for item %i is %f\n", i, e->ranking[i]); 
#endif 
} 
[ $a n nn n-ne em * / 
main() { 
int i; 
randomize () ; 
printf("\nWelcome to the Analytic Hierarchy Process!") ; 
printf("\nLast compiled on %s, %s\n", __TIME__, __DATE__); 
/* Evaluate priority arrays for each element is ‘array! */ 
for (i=0; i<sizeof(array) / sizeof(array[@]); i++) 
get_eigenvector (&array[i]); 
/* Evaluate the tree. The result is returned in array[@].ranking */ 
evaluate_hierarchy (&array[@]); 
--*/ /* Display rankings for each case. The highest score is the winner. */ 
for (i=@; i<N_CASES; it+) 
printf("Case %i has ranking %f\n", i, array[0].ranking[i]); 
return @; 
} 
--*/ 
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There is an easier way! 
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DR. ECCO’S OMNIHEURIST CORNER 


Dig 
Dennis £. Shasha 


few minutes after I arrived in Ecco’s 
apartment, the doorbell rang. A slim, 
fit woman in her late twenties en- 
tered, introducing herself simply as 
Natasha. 

“My last name need not concern you,” 
she explained as she looked us over, siz- 
ing us up with her penetrating blue eyes. 
“ve come to ask your help, Dr. Ecco,” 
Natasha went on. She didn’t sit down, 
though she did balance her briefcase on 
the back of a chair, “But first, I want to 
give you a little background.” 

“We are ready,” Ecco said with a smile. 

“Heinrich Schliemann, the German gro- 
cer turned archaeologist, followed the J/- 
iad to discover Troy. Later, he thought he 
found Agamemnon’s tomb in Mycenae,” 
Natasha began. “He was wrong about 
Agamemnon, but he did find five tombs 
sculpted in gold, so they probably weren't 
shepherd graves. His excavation tech- 
niques were controversial, to say the least. 
He didn’t shy away from dynamite if a hill 
was in the way. He also neglected to share 
the treasures of the Trojan jewel factory 
with the Ottoman Empire in spite of his 
promises to the Sultan. The Ottomans 
protested and demanded 10,000 gold 
francs. He gave them 50,000 instead. He 
was a man in a rush. 

“Well, ’'m a modern archaeologist, so 
you'd expect me to be a brush and silk 
kerchief kind of digger. Usually, Iam, but 
not this time. You see, I’m excavating in 
the Sudan. The country is in a state of civ- 
il war and the authorities are deeply cor- 
rupt. So, I’m a woman in a rush. I’m go- 
ing back tomorrow and I expect my team 
there to have found 12 large specimens. 
We want to smuggle them out of the coun- 
try a few at a time and keep them until 
the Sudan has a responsible government.” 

“You're a thief,” 10-year-old Liane said, 
ever tactful. 





Dennis, a professor of computer science at 
New York University, is the author of The 
Puzzling Adventures of Dr. Ecco (Dover, 
1998), Codes, Puzzles, and Conspiracy 
(W.H. Freeman & Co., 1992), Database 
Tuning: A Principled Approach (Prentice 
Hall, 1992), and (coauthored with Cathy 
Lazere) Out of Their Minds: The Lives and 
Discoveries of 15 Great Computer Scien- 
tists (Springer Verlag, 1998). He can be 
contacted at DrEcco@ddj.com. 
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Ecco nodded, “Quite possibly, Liane. 
How do we know, Natasha, that you’re 
telling the truth?” 

Natasha looked unperturbed and 
reached into her briefcase. “You don’t 
know I’m telling the truth, but here is a 
stack of my publications. I am known as 
a great preserver. The specimens will in 
fact go into a private collection, because 
the U.S. government doesn’t want prob- 
lems with the government of the Sudan 
over the issue. But I assure you we are 
doing this only to preserve the finds, not 
to exploit them.” 

“Why can’t you just leave them in the 
ground?” Liane asked. 

“The site is exposed now,” Natasha said. 
“We are convinced the site will be looted 
if we delay.” 

“What can we do for you then?” Ecco 
said without enthusiasm. 

“Well,” Natasha replied. “As I said, there 
are 12 possible finds. We want to identi- 
fy each of them with a positive whole 
number. When we phone our home base 
we want to use the sum of the numbers 
corresponding to the finds to tell our col- 
leagues which ones to prepare for. They 
may respond with other sums to tell us 
which ones they are ready for. We think 
it’s better to send a sum rather than a se- 
quence of numbers because it will attract 
less attention.” 

“Please give us an example,” Ecco said. 

“Suppose, for example, that there were 
only three possible finds and we labeled 
them 10, 11, and 12, respectively,” Natasha 
replied. “Then, 22 would represent the ob- 
jects labeled 10 and 12, whereas 33 would 
represent all three objects. Altogether, the 
following sums are possible, each of which 
represents a unique set of objects: One 
object could be 10, 11, 12; two objects 
could be 21, 22, 23; three objects could 
be 33 (10+11+12). On the other hand, if 
we had four possible finds, the encoding 
10, 11, 12, 13 wouldn’t work because 23, 
for example, could result from either 
10+13 or 11+12. We want every possible 
sum to mean a different combination.” 

“That’s easy enough if we can use big 
numbers,” Liane said. “For example, 10, 
100, 1000, 10000.” 

“Correct, but that’s just the thing,” 
Natasha replied. “We want the largest pos- 
sible sum to be as small a number as pos- 
sible. If someone hears us talking about 





numbers in the billions, they may think 
we are bank robbers.” 

“Big difference,” Liane said in a loud 
whisper. 

“But if every subset of 12 is possible, 
then the highest possible sum must be 
over 4000,” Ecco said. 


Reader: Why should this be? 


“I see,” Natasha said after she heard his 
argument. “That’s okay, in fact, because 
these finds are so big that we might not 
be able to take out more than three at a 
time. Can you find a labeling that would 
guarantee us a low sum?” 

Ecco found a way to give positive whole 
number labels to the 12 objects such that 
any subset of the objects of size 3 or less 
could be described by the sum of the la- 
bels and that sum would uniquely identi- 
fy the subset. 


Reader: Find a labeling giving the small- 
est maximum sum in that case. Ecco was 
able to find a labeling such that the sum 
of any three never exceeded around 1400. 


After hearing this answer, Natasha 
looked preoccupied. “Come to think of 
it,” she said. “We may be able to get four 
specimens out at a time.” 


Reader: What would be the smallest 
maximum sum in that case? Liane was 
able to find a labeling that ensured that 
the sum of any four or fewer items was un- 
der 3000. 


Natasha asked a few questions, made 
some notes on the written solutions, 
then left. 

Ecco turned to Liane and me, “I under- 
stood why Natasha wouldn't want fractions 
and I suppose she wouldn't permit nega- 
tive numbers to be reported over the phone, 
but I wonder if we could find a way to use 
negative numbers to good effect. Maybe 
some labels could be positive in some cas- 
es (for example, if the sum it participates 
in would be negative otherwise) and neg- 
ative in others. I wonder whether we could 
get a better solution in that case.” 


Reader: If negative labels are allowed 


and labels can be positive or negative de- 
pending on the context, can you achieve 
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better results for the aforementioned two 
questions? 


Dr. Ecco never told me whether this 
idea, in fact, helped. 


Last Month’s Solution 

The solution to the “Fair Swedes” prob- 
lem, which involved mapping of original 
districts to new district numbers, is shown 
in Table 1. A graphical representation of 
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Dr. Ecco’s 28 district solution superim- 
posed on the original map is shown in 
Figure 1. Thus, all areas having the same 
number will belong to the same district 
no matter what the original numbers were. 


Reader Notes 

Many readers found clever solutions to 
the “Directed Evolution” problems 
(November 1998). Here I cite those who 
found the best solutions to the two prob- 
lems. Some people used computers and 
others used pencil and paper. The best 





Figure 1: Ecco’s 28 district solution to 
the “Fair Swedes” puzzle 
superimposed on the original map. 
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algorithms using reversals are polynomi- 
al, but are quite tricky. 

The first problem demanded a solution 
using reversals only. The best answers | 
received required nine steps. The first such 
solution came from Eric Haines who pro- 
posed the following: 


start: mhtvkllcvvfsclceavawasshrqpchsp 
1: (12,19) mbhtvkllcvvfsawavaclcsshrqpchsp 
2: (9,14) mhtvkllcvawasfwvaclesshrqpchsp 
3: (7,14) mhtvkllvfsawavevaclesshrqpchsp 
4: (3,8) — mhtfvilkvsawavevaclcsshrqpchsp 
5: (4,23)  mhtfrhsscleavcvawasvkllvgpchsp 
6: (1,12)  mvaclesshrfthcvawasvkllvqpchsp 


(5,24) mvaclqvllkvsawavchtfrhsscpchsp 
(2,27) — mvhcpcsshrfthcvawasvkllvqlcasp 
(0,17) awavchtfrhsscpchvmsvkllvqlcasp 


8 & > 


Eric also pointed out that this puzzle is 
similar to those in the games section of the 
out-of-print book What to Do Afier You Hit 
Return: A Computer Games Book from the 
People’s Computer Company (People’s Com- 
puter Company and Hewlett-Packard, 1975). 
The pages he sent me talked about rever- 
sals that started from the beginning of the 
string, and thus were a little easier than 
these general reversals. Eric’s Perl code for 
solving the problem is available at http:// 
www lightlink.com/erich/nov98_pl.txt and 
from DD] (see “Resource Center,” page 5). 

Other readers who matched Eric’s feat 
were: Steve Myers, Creig Smith, Ted Alper, 
Charles Taylor, Dean Clamons, Tom Dinger, 
Oscar Schoof, Geldenhuys Jaco, Serguei 
Patchkovskii, and Onno Waalewijn. 

Dr. Burghart Hoffrichter was the first to 
present a seven-step solution for the sec- 
ond problem and to point out that rota- 
tions didn’t help: 


start mhtvkllcvvfsclcavawasshrqpchsp 
rev (5,29): mhtvkpshcpgrhssawavaclesfvvell 
rev (11,25): mhtvkpshcpqvfsclcavawasshrvcll 
rev (5,22): mhtvksawavaclcsfvqpchspshrvell 
rev (3,11): mhtcavawaskvlcsfvqpchspshrvell 
rev (6,11): mhtcavvksawalcsfvqpchspshrvell 
rev (4, 8): mbhtcskvvaawalcsfvqpchspshrvcll 
rev (6, 9): mbhtcskaavvwalcsfvqpchspshrvell 


Most readers agreed, though Creig Smith’s 
solution did use one rotation. Other read- 
ers who showed a seven-step solution were: 
Michael Van Vertloo, Steve Myers, Don Vilen, 
Ted Alper, Charles Taylor and the Wang 
Global Banking Solutions team of Bruce Os- 
carson, Curtis Cooley, Dale Bennett, Tom 
Dinger, Oscar Schoof, Geldenhuys Jaco, Ser- 
guei Patchkovskii, and Onno Waalewijn. 


A Final Note 

The ingenuity of DDJ readers makes this a 
truly delightful column to write. If you have 
a good solution, please send it early in the 
month when the issue comes out, because 
I have to submit my discussion of reader 
solutions during that same month. 


DDJ 
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Small is Beautiful — 


Kind Of 


Gregory V. Wilson 


sometimes think it’s a shame that 

Canadian courts aren't as freewheel- 

ing as their American counterparts 

when it comes to damage suits. If they 
were, I’d probably have sued some big- 
name computer-book publishers by now 
to recover the cost of my chiropractor’s 
bills. Personal computers were supposed 
to make paper obsolete, but the parcels 
I get from publishers, and the contents 
of my pack, seem to get heavier and 
heavier. Perhaps someone could per- 
suade publishers to let books shrink back 
to a manageable size, and grab shelf- 
space by packaging them in large, most- 
ly empty boxes, just like the software 
they describe. 

Until that happens, I will continue to 
take a special pleasure in books that say 
everything they need to in just a few 
pages. David Rozenshtein’s The Essence 
of SOL is one good example of this. The 
book “is dedicated to the proposition 
that one can often accomplish 80% of 
the task in 20% of the time.” In this case, 
the task is learning SQL, and Rozen- 
shtein meets his objective by showing 
how to formulate SQL queries to answer 
13 common types of questions. The 
questions themselves are arranged in or- 
der of increasing complexity, so that (for 
example) negation is explained before 
aggregation, which in turn appears be- 
fore SQL’s handling of NULL is covered. 
The result can be read by a complete 
neophyte in less than two hours, but still 
manages to cover everything needed to 
formulate nontrivial queries against non- 
trivial databases. The writing is overly 
formal at times (the book itself is re- 
ferred to as “this essay,” for example), 
but it is still an excellent, useful little 
guide. 


Greg is the author of Practical Parallel Pro- 
gramming (MIT Press, 1995), and coedi- 
tor with Paul Lu of Parallel Programming 
Using C++ (MIT Press, 1996). Greg can 
be reached at guwilson@interlog.com. 
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The second edition of Tom Negrino and 
Dori Smith’s JavaScript for the World Wide 
Web is longer and much glossier than The 
Essence of SQL, but just as useful. Like 
Rozenshtein, the authors teach by exam- 
ple. Each technique is introduced by 
showing a page that uses it, then ex- 
plaining the corresponding JavaScript 
source line by line. Color is used spar- 
ingly, but effectively, to highlight points 
of interest, and the code samples are read- 
able despite their small size. All of 
JavaScript’s commonly used capabilities — 
highlighting icons as they are brushed by 
the user’s mouse, controlling the content 
of one frame from another, checking user 
input, and handling cookies— are cov- 
ered, and links to further examples at the 
book’s web site are plentiful. 

Tom Christiansen and Nathan Tork- 
ington’s The Perl Cookbook is several 
times larger than either of the previous 
books, but no less useful. Perl is a com- 
plex language, even by computing’s 
rather forgiving standards; descriptions 
of it are littered with words like “except,” 
“unless,” and “however.” While the lan- 
guage’s motto might be, “There’s more 
than one way to do it,” beginners and 
harassed web site administrators would 
often be happy to be shown just one, so 
long as it worked. 

Enter The Perl Cookbook. Each of its 20 
chapters contains a dozen or more sec- 
tions, each of which is has “Problem,” “So- 
lution,” “Discussion,” and “See Also” head- 
ings. The “Problem” descriptions are 
typically quite brief, as in: 

You have a dat file containing comma- 
separated values that you need to read in, 
but these data fields may have quoted com- 
mas or escaped quotes in them. 


The “Solution” presents at least one 
way to do what’s required, and often 
shows a couple of alternatives as well. 
Solutions are taken from common prac- 
tice, other O’Reilly books on Perl and 
regular expressions, or from widely used 
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(continued from page 135) 

Perl modules— the best answer to the 
aforementioned problem, for example, is 
to use the quoteword function from the 
Text:ParseWords module. 

Other problems posed and solved in 
this book include passing parameters by 
name (instead of position), extracting 
values from C header files for use in Perl 
scripts, and handling TCP connections 
in client/server systems. The writing is 
clear, concise, and thankfully free of in- 
jokes, and the 22-page index and “See 
Also” links always led me to the answers 
I wanted with a minimum of fuss and 
backtracking. If only it was small enough 
to carry around without back strain. 

The Perl Cookbook is the sort of refer- 
ence and how-to that we’ve come to ex- 
pect from O’Reilly, but as Kevin Dowd 
and Charles Severance’s High Perfor- 
mance Computing shows, the company 
can put out a good survey when it wants 
to. The surtitle on the cover of this book 
says, “RISC Architectures, Optimization & 
Benchmarks,” but the book covers a lot 
more than this. In fact, it covers just about 
everything that someone doing numeri- 
cally intensive programming, such as 
statistics, graphics, or signal processing, 
needs to know about modern desktop 
computers. 

The first section describes modern com- 
puter architectures: What RISC is and isn’t, 
how memory subsystems are organized, 
what effect they have on performance, 
and how floating-point numbers are rep- 
resented and manipulated. The second 
section, “Programming and Tuning Soft- 
ware,” starts with a good summary of 
what compilers do to optimize programs, 
and what the limitations of current- 
generation commercial optimizers are. The 
other three chapters in this section look 
at timing and profiling, ways program- 
mers can eliminate clutter that might pre- 
vent automatic optimization, and what 
can be done to make loops run faster. 
Since loops over arrays of values consume 
most of the time in number-crunching 
programs, this chapter is especially worth 
reading. 

The third and fourth sections move on 
to parallel programming. Shared-memory 
multiprocessors, which are now afford- 
able even for desktop use, are covered 
first, along with ways programs can be 
tweaked to take advantage of such hard- 
ware. More esoteric architectures and spe- 
cialized programming languages are next. 
Having worked in this field in the 1980s, 


I was a bit depressed to see how little: 


progress has been made, but that takes 
nothing away from the clarity and use- 
fulness of the book. 

The final section discusses benchmarks, 
and the pitfalls of benchmarking, while 
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the appendices touch on threading in For- 
tran, Intel’s next-generation IA-64 pro- 
cessor, and a variety of other topics. Over- 
all, the book is very well written, very 
informative, and very good at focusing on 
the things that practicing programmers ac- 
tually need to know. I only wish it had 
been available 15 years ago, when I first 
needed to learn all these things. 

The last two books in this month’s re- 
view have less to say about the details of 
particular languages, and more about how 
to go about designing and building large 
software systems. Or, in the case of Anti- 
Patterns: Refactoring Software, Architec- 
tures, and Projects in Crisis, how not to 
do this. Design patterns are one of the 
bigger bandwagons to come along in the 
last 10 years. Since the publication of the 
“Gang of Four” book, it has become fash- 
ionable to try to label anything that any- 
one has done more than once as a pat- 
tern. This book is therefore doubly 
refreshing, both because its authors aren’t 
trying too hard, and because it’s always 
fun to see dirty laundry aired in public. 

So what is an antipattern? Lava Flow is 
probably the best example. The anecdo- 
tal evidence teaser at the start of the chap- 
ter on this section reads: 


Oh that! Well Ray and Emil (they’re no 
longer with the company) wrote that rou- 
tine back when Jim (who left last month) 
was trying a workaround for Irene’s input 
processing code (she’s in another depart- 
ment now, too). I don’t think it’s used any- 
where now, but I’m not really sure. Irene 
didn’t really document it very clearly, so we 
figured we would just leave well enough 
alone for now. 


A Lava Flow is a program that has 
grown by accretion. Instead of throwing 
away code, successive waves of engineers 
have wrapped it, buried it, or worked 
around it, until only a small fraction of the 
code in the program actually does any 
useful work. The problem, of course, is 
that no one knows which fraction, and so 
the cycle continues. 

As with most other books in the area, 
the authors describe each pattern in terms 
of its general form, symptoms, typical 
causes, and possible solutions. Unlike most 
other books, the authors of AntiPatterns 
include software project management in 
their remit, and describe such common 
catastrophes as “Death By Planning” and 
“Smoke and Mirrors.” I found these sec- 
tions much less interesting than the oth- 
ers, and felt they should have been saved 
for a second book. I also felt, looking 
back, that there was less substance in the 
book than I had thought when reading 
through it: More examples, and even a 
few question-and-answer problems, would 
do a lot to alleviate this. 


Finally, Jesse Liberty’s Beginning Object- 
Oriented Analysis and Design is hard to 
label, but a very good book nonetheless. 
His earlier Clouds to Code was a journal- 
like description of the development of a 
medium-sized commercial application. 
This book is more like a textbook, but is 
still very practically oriented. As the “In- 
troduction” says: 


When methodologists write their books, 
they must be exhaustive...[which] makes 
it all too easy for the reader to get lost in 
the details...[T]his book...is a working- 
programmer’s guide to building com- 
mercial software using state-of-the-art ob- 
ject-oriented analysis and design. You will 
see how software is conceived, how you 
build a requirements document, how you 
make the “build/buy” decisions. ..[and] how 
to translate an object-oriented design into 
solid and reliable C++. 


That’s a pretty tall order, but Liberty 
manages to carry it off. The book really 
does show what analysis is, how to go 
about formalizing the user’s understand- 
ing of a problem domain (not least so 
that the user’s expectations can be con- 
tained), and how to translate all of that 
into a design for a program, and then 
into an actual program. The author uses 
the recently standardized Unified Mod- 
eling Language (UML) notation, and is 
up front about saying that for most com- 
mercial software developers, 32-bit Win- 
dows and MFC are the only platforms 
that matter, so you might as well get used 
to them early. 

While it is the best general introduc- 
tion to object-oriented analysis and de- 
sign that I’ve come across yet, the book 
does have two significant flaws. The first, 
and smaller problem, is that some of the 
material on concurrency and persistence 
seems out of place. While these things 
are a necessary part of today’s real-world 
applications, I think the book would have 
been stronger if it had focused on things 
that other books don’t cover this well. 

The second flaw is more important. 
Simply put, this book is not structured 
as a textbook. There are no questions at 
the end of the chapters, which would 
make it difficult for an overworked col- 
lege instructor to use this book in a 
course. I think that’s a shame, particu- 
larly since other books in this area (such 
as McConnell’s now- classic Rapid Devel- 
opment and Software Project Survival 
Guide) have the same shortcoming. Per- 
haps there’s room here for someone to 
write a cookbook. 

But then, that would just add to the 
weight in my pack. 


DDJ 


137 


 Sanscript - [Hello World 


Ej fle Et ew Ioan Ee “ pe nPop e Program with 
pictures, not code! 


2 Can wersions 
& £3 DOE 
£3 Decanai 
0% Deecto aie Cigesey Meany 


Bee | | * Use with ACT!, Word, 
Excel, Powerpoint, or 
es fl) any COM-enabled 


J & i fm 4) application! 


Fee Cran 


Use our development tools with 
IBM ARTIC serial communication 
adapter cards. 

You gain from multiple ports, 
multiple protocols on a single 
card, CPU independence, and 
portable card development in C. 

For Windows NT, Win 95, 
DOS, OS/2 and ONX. 


isync, async, frame relay, X.25, BX25, 
LAP-B, HDLC/SDLC, & custom protocols. 


Jax 805-966-7630 Se @ 
elephone 805-966-6424 my Guadr on 
email info@quadron.com © © WWwwW.quadron.com 


Upgrade to 4Keeps” V2.2! 
Design and document databases in Style! 


Use 4Keeps™ with Visio® Professional for 
Modeling Power: Reverse-engineer & generate 
relational databases - Now with direct support 
for Access and ODBC support for major RDBMS! 

Move from ERDs to OO class diagrams, with the new Shapeshifter” wiz- 

ard! Use any of 10 methodology styles — 

including UML! Model inspection is easy 

with 4Keeps hyperlinked error correction! 

Produce detailed documentation with 

embedded graphics for paper or the Web! 


4Keeps V2.2 Upgrade $99 - Single license- $349 - 5 pack - $1,450 


1.888.971.0250 x203 © sales@adexperts.com * www.adexperts.com 





ae 
8 oe eae 


i 
Borer sr ais 


Beet 
Binney 
prensa 


Easily add professional bar . 
coding capabilities to Windows | 


3.1, 95 and NT applications. 
Royalty-Free. 


Create extremely high quality, 
device independent, WMF a 52A56"78001 
graphics. Not fonts! Not bitmaps! 


800-722-6004 
www.taltech.com/ddj.htm 


Y A Polyglot IDE! 
V Scalable Printing! 


Flowlvnx — ~ Visual Studio”6.0 Add-in! 


forenoon) 


v Language Customization! 


Virual FlowCoder is a trademark of Flowt yin, ic. - Ali rigttts 


te — 


Be 








TV 0) ofe) a th 
Windows NT, 
Windows 98, 
Tate loys 

MS-DOS, 

& Windows 3.x 


Where do 
you find 116,000 pr 





© 5 Stee a: 





( Set 


a eee By RSE eye 
aev e ODI 


ee 
ee 


z Rees 


ey 


33; 
= 


Bae 


ee 
Le 


ith 
Hae 
Celts 





oo 


Dr. Dobb's Electronic Review 
of Computer Books! Pherk Tt (ut! 


@ Independent reviews of technical computer books 
@ Written BY developers FOR developers 


SSS 


i 
igi 


ee 
His 


iit 


4 
bea 


| i a 
ee 


“ ceen baer Te tam 
ay ci ieee Mate ae 


Thieme centre fas 


a 


iiss ish 

Py 

He abe: 
1 


a 
ae 


su 


a 


=pBooksm To order books in this magazine or, any book. Please call 24 hrs/365 days: (800) BOOKS-NOW (266-5766) or 

Ow (702) 258-3338 ask for ext. 1410 or visit us on the web at http://www.BooksNow.com/Dr.Dobbs. Use Visa, M/C 
. sm or AMEX or send check or money order + $4.95 S&H ($2.50 each add'l item) to: Books Now, 448E 6400 South, 
Virtual Bookstore™ s.._ 4195 salt Lake City, UT 84107 








JavaScript Objects 


This is a book of JavaScript tools and 
projects for people who make web pages, 
and the programmers and future pro- 
grammers who work with them. Makes 
object-oriented programming accessible 
and understandable. 


WROX PRESS 


Authors: Myers & Nakhimovsky, 1-861001-89-4, 
$39.99 Visit your local bookstore or view a full TOC and 
gama sample chapter at www.wrox.com 1-800-USE-WROX. 


— www.dinkumware.com 





maelicteielatel 


er: 


Embedded 
Compilers 
& 
DYNA Keto) (5 








CAD-UL USA GERMANY 


Ph. 602-945-8188 Ph. +49 731 93760-0 
us.sales@cadul.com UK sales@cadul.com 
Ph. +44-1291-626267 


uk.sales@cadul.com 


Add ZIP/UNZIP power to your Windows app’s. 
Now supporting Active Server Pages (ASP)! 
DynaZIP is the industry leader for zip compatible 

data compression, millions in use daily. 


Active Delivery is the answer when you wantto add 
self-extracting zip file creation to your applications. 
All products have a full 30-day no risk guarantee. 
Inner Media, Inc. 
mos! 60 Plain Road, Hollis, NH 03049 
(800) 962-2949 

(603) 465-3216, Fax (603) 465-7195 

www.innermedia.com 





: New! 








MTIP (Multi-Threaded Image Processing) 


A visual Image Processing Windows 95/NT Environment with 
ISO 12087 (PIKS) modules 

The MTIP environment assists both professional and students in 

developing and testing Image Processing algorithms, prototypes and 

applications by automating many of the tedious details of setting up an 

image processing environment. 





* Advanced Image Processing on your PC at low cost. 
* Drag and Drop Visual Programming. 
* Comprehensive Support for N-Dimensional, Multispectral Datasets. 


f° Rich collection of well-documented ISO 12087 (PIKS) based Image 


Processing Operators. 
* Rich API for Developing your own Drag and Drop modules using C or C++. 


P.O. Box 2865 Tel.: +47 73929440 
Dynamic N-7002 Trondheim Fax: +47 73516325 


Imaging AS E-Mail: sales@dynamic-imaging.no 
Web: _ http://www.dynamic-imaging.no 


Predict Software Speedup 
FREE software accurately 
predicts the code speedup possible 
from parallelization. 


Download at - www.myrias.com 
Call (403) 435 - 1000 


Myrias Software Corp. 





@ Code Co-op. 


The first fully distributed Version Control System 


* No LAN or central server required 

* Synchronization through email 

* Intuitive GUI -- check-in, check-out, synch, visual diff. 
° Free technical suppport 

* Download fully functional trial version from our website 


SERVER-LESS VERSION CONTROL 


www.relisoft.com 


& Reliable Software. 


Smart Tools for Smart Programmers », 











Version 2.0 


WANDS 


the wizard wizard f 


- Build, run and maintain wizards 
i - Solve complex UI problems 


- Meet business needs, make users happy 
- GUI designer, lightweight run-time 


fm - ActiveX, DLL, VCL 
j - VB/VBA, Delphi, C, C++, Java, WinHelp... 
- Free fully functional trial version 


INGENge! NQinc. www.ingeninc.com 


734/662-4646 















Zip and Unzip from your apps with the 


XCEED ZIP |ze 


COMPRESSION LIBRARY lL. 


e Easy to use VBX, OCX and VCLs 
e Fast, compact and reliable 

e Over 40 Zip and Unzip functions! 
e All 16 & 32-bit controls for $199.95 
New self-extractor add-on for Xceed Zip lets your 


apps create customized 16/32-bit self-extracting 
Zip files. Only $99 with purchase of Xceed Zip! 


Get the fully functional free trial version! 
www. xceedsoft.com/dobbs 


Xceed Software 1-800-865-2626 1-450-442-2626 


» New -Version 2.1. 
» Generates documen- 
tation. directly from the 
source code. 

> Extracts comments. 

> User customized 

reports formats. 

> HTML, WinHelp, 

RTF. 


b> FREE working 
evaluation at 
1-888-646-1933 www.bbeesoft.com 
Bumble Bee Software i 
P.O. Box 2007 
Westford, MA 01886 


info@bbeesoft.com 








ae 


* Earn B.S. and M.S. in Computer Science rere 

- : AMERICAN 
* NEW B.S. program in Information Systems INSTITUTE 
* Distance Education EEE 
* Object oriented B.S. program SClENE RS 
* Approved by more than 275 companies a : 
* Follows ACM/IEEE guidelines STATE LICENSED 
* Thousands of students throughout U.S. indian icon 

ACCREDITED 

World Association 


of Universities 
and Colleges 


Free catalogue 1-800-767-AICS 
or www.aics.edu 


VICTOR 


Image Processing Library 


Fast BMP, TIFF, PCX, GIF, TGA, PNG, JPEG. Adjust 
brightness, contrast, sharpen, create filters, resize, rotate, 
+more of single image, multiple images, or any image area; 
color reduction to optimum, specific, or std. palette; print; 
scan; crop, combine, compare, blend images. 


DOS $199, 16-bit DLL $299, 32-bit DLL $499 


Catenary Systems 
314-962-7833/fax: 314-962-8037 
www.catenary.com/victor 
ask for free demo SIC avail visa/mc/c.o.d. 





mae DLO) AN | ROYND). 


The Simplest Way to Create Java... 


Simplicit ity 


* The Code Sourcerer™ writes Java code for you 
* Executes any Java code on-the-fly without compiling 
* Supports all AWT & Swing components 

* Import any JavaBeans™ 

* Certified 100% Pure Java™ by Sun Microsystems 


www.datarepresentations.com 











Create Prolog = 
Components © 


Diagnose, advise, configure and plan Pee) 


with the Amzi!® LogicServer™ tools & 
libraries (DLLs) for C/C-+, Java, VB, a 
Delphi, Web Servers & more. Win NT @™% 
95 3.x & Solaris. Use ODBC, Sockets, r 
Unicode & new OOP extensions. 

FREE Evaluation Version! 
Amizi? ine. 
Cali +1-513-425-8050 





Email info @ amzi com 
Fax 425-8025 


Sead liticla ke) a 


Copy Protection Electronic Software Distribution © License Management 


Features: 


* 


Wraps Your Software in Minutes 

* Try-Before-You-Buy & immediate Purchase 
* Software Metering & Rentals 

* Windows & Macintosh Compatibility 

* Foreign Language Support 

* Key Diskette Option 

Sales: (408} 297-7444 ext,} 


www.paceap.com 


© 1998 PACE Aati-Pirocy. All rights reserved worldwide. latertok is a trademark af PACE Anti-Pirec Y 


Reliable Software Security| 


a ° C-CALL ($69) Graphic-tree of caller/called function hierarchy, cross-reference, 


Cost effective products for all 
levels of software protection 
and authentication. 


@ CRYPTO BOX? brand dongles, 
SmartCard, PC Cards, and extension 44a 
cards ® Software based metering 9% 


systems @ Active, OCX & VCL 


components 
® ]-800-627-9468 


770-986-8887 
SOFTWARE SECURITY — FAX: 770-986-8891 











**aADMJOS ANOX PUDISAIPU/) | 








Smartcard Solutions 


The SMARX-Card Developer’s Kit . are 
provides everything needed to _ his 
create smartcard applications 

for the next millennium. 

@ Easy to implement under DOS and 

Windows ® Controls access to PC/ 

data/network @ Protects and meters 

software @ Secures electronic com- 





merce @ Supports ISO 7816 andT= 
0/1/14 @ Compatible with Microsoft 
PC/SC 


[VA ® 1-800-627-9468 
SOFTWARE SECURITY FAX: 770-986. 


TY FAX: 770-986-8891 


Understand For C++ 


Analyzes your C++ source code to help you 
quickly understand your software. 


¢ Hypertext source & Class Browser 

* Detailed Interactive Cross Reference 

¢ Invocation, Include, Declaration Heirarchy Charts 
* HTML Publishing of Code & Analysis 


* WYSIWYG pminting, Clipboard & Bitmap Output 


Download your Jie 
eval copy today. 
wwwscitools.com Scientific Toolworks, Inc. 


Phone: (603) 298-5905 21 Technology Drive Ste #4 
Fax: (603) 298-5910 West Lebanon, NH 03784 





C and C++ DOCUMENTATION TOOLS (v. 7.0) 





file/function index. 


2° C-CMT ($69) Creates/inserts/updates comment-blocks (functions/identifiers 


used) for each function. 


fa ¢ C-METRIC ($59) Calculates path complexity, counts lines with comments, code, 


'C’ statements. 


a © C-LIST ($69) Lists and action-diagrams, or reformats source into user-selected 


standard formats. 
© C-REF ($69) Creates cross-reference of local/global/define/parameter identifiers. 


 C-DOC ($199) PACKAGE All 5 programs integrated as DOS program. <10,000 
lines. C-BROWSE Windows graphic-tree viewer. 


: @ ¢ C-DOC Professional ($299) DOS, Windows, 0S/2, 1,000,000+ lines. 
= ° NEW VER 7.0! WEB HTML REPORTS! 


i SOFTWARE BLACKSMITHS INC. 


email @ swbs.com 


Voice/Fax (905) 858-4466 


http://www.swbs.com 


6064 St Ives Way, Mississauga 
ONT Canada L5N-4M1 








OF INTEREST 








MicroEdge Visual SlickEdit 4.0 is a multi- 
platform editor for UNIX, OS/2, and 
OS/390. Version 4.0 features include Con- 
text Tagging, DIFFzilla for file differenc- 
ing, FTP support, and PL/SQL and Trans- 
act SQL support. Visual SlickEdit 4.0 for 
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BeOS Release 4 from Be is an operating 
system designed for digital content cre- 
ators. BeOS Release 4 features a Media 
Kit, which lets users specify complex se- 
ries of operations to be performed on 
streaming media, and lets developers pro- 
gram high-performance, low-latency me- 
dia applications, expanded hardware sup- 
port; support for the Windows FAT16 and 
FAT32 filesystems; built-in TCP/IP net- 
working; and improved overall system per- 
formance. BeOS Release 4 runs on PCs 
(Intel Architecture or Power PC) with a 
minimum of 16 MB of RAM; 150-MB hard 
disk or hard-disk partition; CD-ROM drive; 
keyboard and mouse; built-in or bundled 
compatible video adapter; multisync mon- 
itor (recommended); and network con- 
nection via Ethernet or PPP. BeOS Release 
4 costs $99.95. 

Be Inc. 

800 El Camino Real, Suite 400 

Menlo Park, CA 94025 
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Green Hills Software has released Code- 
Balance, an optimizing profiler for its C, 
C++, and EC++ compilers. CodeBalance 
targets 32-bit CPUs equipped with 16-bit 
instruction-set extensions, using a mix of 
32- and 16-bit instructions to reduce code 
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size while maximizing execution speed. 
You can optimize programs for small size, 
high speed, or any combination. For ex- 
ample, programmers can direct CodeBal- 
ance to optimize for the fastest possible 
performance given a particular code size 
reduction goal. Similarly, you can direct 
CodeBalance to optimize for the smallest 
possible code size given a particular min- 
imum 32-bit performance level. CodeBal- 
ance uses a mix of 16- and 32-bit in- 
structions to achieve the desired results. 
CodeBalance is currently available for the 
ARM7/TDMI and MIPS16 processors, both 
of which provide 16-bit extensions. Code- 
Balance is bundled with the MULTI De- 
velopment Environment, which includes 
a C/C++/EC++ compiler, assembler, link- 
er, and instruction set simulator. A single- 
seat MULTI developer’s license costs 
$5900.00 for Windows 95/NT, and $8900 
for UNIX hosts. 

Green Hills Software Inc. 

30 West Sola Street 

Santa Barbara, CA 93101 

805-965-6044 
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Riverace’s ACE Version 4.6 is a freely avail- 
able, portable C++ class library for devel- 
oping distributed, concurrent applications. 
Version 4.6 features ports of ACE to Win- 
dows CE and pSOS, as well as bug fixes 
and new features. ACE is freely available 
from Riverace’s web site. Riverace pro- 
vides software support for ACE. 
Riverace Corp. 

27 Short Street 

Franklin, MA 92038 

508-541-9180 

http://www.riverace.com/ 


Lockheed Martin Federal Systems has re- 
leased its High Availability Real-time Dis- 
tributed Package (HARDPack), a real-time, 
fault-tolerant, high-performance CORBA 
ORB. HARDPack’s CORBA implementa- 
tion bundles CORBA services such as 
naming, event, lifecycle, and externaliza- 
tion, as well as several custom extensions 
for real-time fault tolerance. 

Lockheed Martin Federal Systems 

1801 State Route 17C 

Owego, NY 13827 

607-751-2000 
http://www.hardpackorb.com/ 


GoAhead Software has announced the 
GoAhead Embedded Management Frame- 
work for Windows CE. The Embedded 
Management Framework consists of the 
FieldUpgrader for upgrading software in 
the field; WebAccess, an embedded web 
server; and FaultManager, a fault-detection 
and diagnosis application. The Embedded 
Management Framework is also avail- 


able for Windows NT/95/98, VxWorks, 
and UNIX. 

GoAhead is also distributing the source 
code for its embedded web server, Infu- 
sion, free of charge. Infusion, which is a 
subset of WebAccess, supports Active Serv- 
er Pages and JavaScript, and is available 
from the GoAhead web site. 

GoAhead Software 

8652 154th Avenue NE 
Redmond, WA 98052 
425-882-1900 
http://www.goahead.com/ 


JavaMaker from Crystal Systems Solutions 
is a legacy software migration tool that au- 
tomatically converts Cobol applications to 
Java applications. JavaMaker is fully cus- 
tomizable and is licensed on the basis of 
cost per line of code converted. 

Crystal Systems Solution Ltd. 

6 Maskit Street 

Herzliya, Israel 46733 

972-9-952-6100 
http://www.cobol2java.com/ 


Infraworks has introduced an SDK for 
monitoring and controlling the Windows 
file system. InfraModules currently includes 
infraSave, infraDelete, and infraPrint, which 
allow application developers to monitor, 
intercept, and inject their own real-time 
functionality during Windows’ file system 
calls. The infraModules SDK consists of 
device drivers, ActiveX components, and 
sample applications. 

Infraworks Corp. 

P.O. Box 684623 

Austin, TX 78768 

512-583-5000 

http://www .infraworks.com/ 


The Object Management Group’s (OMG) 
“CORBA Academy Tutorial” training pre- 
sentation is available for download via its 
web site. The OMG’s CORBA Academy 
Tutorial is aimed at teaching the basics of 
OMG’s Common Object Request Broker 
Technology (CORBA) and how to imple- 
ment it. The course was developed by Jon 
Siegel, Director of Domain Technology at 
OMG and author of the book CORBA Fun- 
damentals and Programming. The COR- 
BA Academy Tutorial is free to OMG mem- 
bers at http://www.omg.org/members/ 
accept.htm. 

Object Management Group 

492 Old Connecticut Path 

Framingham, MA 01701 

508-820-4300 

http://www.omg.org/ 


Servertec has announced a new release 
of iScript, a scripting language written in 
Java for creating scalable, server-side, 
object-oriented enterprise solutions. This 
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release includes iScriptServlet, a Java 
Servlet for directly accessing iScript from 
any web server supporting Java Servlets. 
The release also includes bug fixes and 
updated documentation. The iServer pre- 
view release is available for free from 
Servertec’s web site. 

Servertec 

18 Oakwood Avenue 

Kearny, NJ 07032 
http://www.servertec.com/ 


Compuware’s NuMega TrueCoverage is a 
code coverage analysis tool for Visual Ba- 
sic, Visual C++, and Java applications for 
Windows 95/98/NT/CE. In addition to com- 
prehensive coverage analysis, TrueCover- 
age features project-wide data merging, 
code-base stability tracking, and multilan- 
guage and platform support. 
Compuware Corp. 

31440 Northwestern Highway 
Farmington Hills, MI 48334 
800-521-9353 


http://www.numega.com/ 


BitJazz is shipping PhotoJazz, a $99.00 
lossless compression plug-in for use with 
Adobe tools including Photoshop, Illus- 
trator, ImageReady, and ImageStyler. Pho- 
toJazz, according to BitJazz, achieves an 
average compression ratio of 2.5 to 1. Bit- 
Jazz is also shipping its cross-platform Bit- 
Jazz SDK, which lets you include Photo- 
Jazz support in Windows and MacOS 
software. The cross-platform SDK includes 
all PhotoJazz interface files, working ANSI 
C sample code, and documentation for 
both platforms. PhotoJazz Pro costs $99.00, 
and PhotoJazz Lite costs $49.00. A free 
PhotoJazz file reader for Macintosh and 
Windows is available from BitJazz’s web 
site. A royalty-free developer's license is 
available for the PhotoJazz SDK. 

BitJazz Inc. 

PO, box 5/0 

San Geronimo, CA 94963 

415-642-4829 

http://www. bitjazz.com/ 


Wilson WindowWare is shipping WinBatch 
Studio, its IDE for WinBatch scripting and 
batch control language for Windows. With 
WinBatch Studio, WinBatch provides a vi- 
sual programming interface. The entire 
WinBatch Library of functions is available 
from the right click menu in WinBatch Stu- 
dio. Other features include color-coded 
syntax display, context-sensitive help, step- 
by-step code execution with variable 
watch window, and macro control. En- 
hanced WinBatch programming functions 
include Internet access scripting, cross- 
application ODBC database scripting, se- 
rial communications scripting (including 
port, modem, and file transfer manage- 
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ment), and (for users of Windows 98 or 
IE 4.0) glamorous HTML dialogs. En- 
hanced functions for manipulating files 
also includes new handling of files with 
UNIX and Macintosh formats. A complete 
list of the new capabilities is available from 
Wilson WindowWare’s web site. WinBatch 
with WinBatch Studio costs $99.95 for a 
single user. The WinBatch+Compiler pack- 
age is $495.00 (including WinBatch Stu- 
dio, WinBatch single user, and the Win- 
Batch Compiler) and is royalty free. 
Wilson WindowWare Inc. 

5421 California Avenue SW 

Seattle, WA 98136 

206-938-2734 

http://www. winbatch.com/ 


Ixla Limited has released Version 2 of its 
Digital Camera Interface (DCD SDK. The 
SDK lets you integrate digital cameras into 
your software applications. New features 
in Version 2.0 include direct support for 
125 digital cameras and the ability to con- 
nect digital cameras directly to web sites 
without any additional end-user software. 
The software works with Visual C++, Vi- 
sual Basic, and Delphi. The Ixla DCI SDK 
2.0 is currently available for Windows 
95/98/NT. Prices are tiered and range from 
$2000 to $100,000. 

IXLA Limited 

17 Jansen Street 

Danbury, CT 06810 

519-884-3301 

http://www.ixla.com/ 


Whole Tomato Software has released a 
new version of Visual Assist, its editor 
plug-in for Microsoft Visual C++ 6.0. Us- 
ing dynamic parsing, Visual Assist en- 
hances Microsoft’s Intellisense with fea- 
tures such as Typo Warnings, Suggest 
Word, ToolTips, and Auto Correct Case. 
VisualAssists’s Complete Word feature 
works on all symbols in an application, 
and its Auto Parameter Info also works 
for macros that take arguments. Visual As- 
sist is available for Microsoft Visual C++ 
5.0/6.0. It costs $189.00. 

Whole Tomato Software Inc. 

P©), Box 513 

Cupertino, CA 95015 

408-323 -1590 


http://www.wholetomato.com/ 


NewMonics has announced the PERC In- 
tegration Kit for Integrated Systems’s pSOS 
real-time operating system. PERC is a 
clean-room Java implementation with 
unique memory-management capabilities 
for real-time embedded systems. The In- 
tegration Kit contains a customized PERC 
virtual machine that, according to New- 
Monics, supports real-time garbage col- 
lection and deterministic real-time task- 





ing. The Integration Kit also contains a 
tool for storing class files in ROM memo- 
ry and a tool for integrating native meth- 
ods. The PERC Integration Kit supports 
pSOS versions 2.2.2 and above on a Pow- 
er PC or 68000 chip. 

NewMonics Inc. 

2625 N. Loop Drive, Suite 2120 

Ames, IA 50010 

515-296-0897 


http://www.newmonics.com/ 


Frontline Test Equipment’s Serialtest Com- 
Probe for Windows 95/98 is a data and 
protocol analyzer for troubleshooting both 
synchronous and asynchronous data com- 
munications. Serialtest turns Windows 
95/98 PCs into serial data and protocol 
analyzers. Protocols decoded include 
Frame Relay, HDLC/SDLC, X.25, SNA, 
Bisync, PPP, SLIP, and TCP/IP. The Serial- 
test ComProbe for Windows 95/98 in- 
cludes Serialtest software and the RS-232 
ComProbe adapter. Serialtest ComProbe 
costs $1695.00. 

Frontline Test Equipment Inc. 

P.O. Box 7507 

Charlottesville, VA 22906 

804-984-4500 

http://www.fte.com/ 


Diab Data’s Fast] is a high-performance 
Java compiler that compiles both Java 
source code and bytecode to native in- 
structions. Fast] offers configurable 
garbage collection schemes, configurable 
libraries, and extensions to Java for sup- 
porting user-allocatable memory, and di- 
rect addressability. FastJ is fully compliant 
with the Java 1.1 language specification. 
Supported microprocessors include Pow- 
er PC, 68K, CPU32, ColdFire, and MCORE. 
Supported hosts include Windows 95/98 
and NT, Solaris, SunOS, and HP/UX. Pric- 
ing for Fast] starts at $2400 for a single- 
user node-locked license. 

Diab Data Inc. 

323 Vintage Park Drive 

Foster City, CA 94404 

650-571-1700 

http://www.ddi.com/ 


Hewlett-Packard’s recently announced 
Chai Developer Kit is a virtual machine 
that complies with the Java Virtual Ma- 
chine specification. At the same time, HP 
announced its ChaiServer, an embeddable 
web server written in Java. 
Hewlett-Packard 

3000 Hanover Street 

Palo Alto, CA 94304 

408-447-1208 

http://www.chai.hp.com/ 
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SWAINE’S FLAMES 





The Flip Side 


was performing my customary magic with the bar rag on all the horizontal surfaces at Foo Bar, the 
: late-night joint where I moonlight as relief bartender to pick up tips from the occasional Silicon 

Valley luminary and the rag-tag pack of journalists who frequent the place, when Flip Nudge, one 
of the rag-taggiest of the pack, strode in, pulled up a stool, and tossed his fedora on the bar. 

“Well, I've uploaded my premiere Nudge Report column to Swaine’s World,” he announced 
with his lopsided grin as he watched me construct the first Cuba libre that he would consume that 
evening. “You can expect your hits to triple immediately. At least.” 

Flip Nudge is the new columnist I had just hired to offset the liberal bias at my web site, 
Swaine’s World (http://www.swaine.com/). You’ve probably heard of The Nudge Report. If not, I 
should explain that the “u” is pronounced like the “ou” in “could,” and “Flip” refers to both his 
attitude and his accuracy: He’s as accurate as a coin flip. 

“[’m sure there will be some increase in the hit rate,” I said. “You do have a following.” 

“Yeah. I’m an urban legend in my own time. Huhn huhn huhn.” 

“Right. Um, I don’t want to hurt your feelings, Flip —” 

“Not possible. I’ve got a hide like a water buffalo.” 

“I’ve noticed the resemblance. Well, according to the Los Angeles Times, the general run of 
online reporting is falling way short of the journalistic standards of other media.” 

“Yeah, I read that report. I can quote reports, too. Bloomberg News says that over 80 percent of 
online news consumers trust online news as much as or more than those precious ‘other media’.” 

“That could be a reflection on the intelligence of online news consumers,” I said. 

“Maybe so, but both those stories were published where?” He tapped my chest. “Online, Mikey. 
Think about it.” 

“Those ‘other media’ don’t address my audience,” he went on. “They’re produced by and for 
the elite East Coast intellectual tree-hugging atheist pornographer tax-and-spend quiche-eating 
labor union/gangster feminist fringe. Refill.” 

I removed his glass, squeezed the lime, and measured the rum and RC Cola into a fresh 
tumbler. “Whereas you write for—” 

“Joe Sixpack and the Littlke Woman. The real 9-to-Sers of America, Mikey, the slubber doffers 
and leguillion debeaders. The salt of the earth.” I was pretty sure the leguillion debeaders were 
unionized, but I didn’t press the point. “How’s the impeachment effort going?” 

“Great! The DNA evidence is conclusive. I’m uploading an exclusive on that later tonight.” 

I moved down the bar to fill orders for Larry, Mo, and Joe, who had come in while Flip was 
talking. When I returned, he needed another refill and I took care of it. “You know, Flip, there are 
those who would say that trying to impeach Thomas Jefferson retroactively is quixotic.” 

“And there are those who would say that Intel investing in Red Hat Linux is quixotic.” 

I grinned. “I’m onto you, Nudge. You think that if you mention technology, you can write these 
Cuba libres off as a business expense.” 

“Yeah, and I’m gonna expense them to Swaine’s World. Huhn huhn huhn.” “Wait a minute—” 

“Jesse Berst, that Ziffyboy columnist, thinks Intel is conspiring to tank Microsoft by taking a 
stake in Red Hat. But I’ve got it from a reporter at Forbes that the support of Linux could backfire 
on Intel. He thinks the spread of Linux will encourage people to keep those old 386s, which is 
definitely not what Intel wants.” 

Paul Piescik came in and I poured him a glass of Slurm. 

Flip was holding the peanut dish upside down when I returned, demonstrating that it was as 
empty as his glass. I filled both. “That would be a fine irony, wouldn’t it?” he asked. “By the way, 
I agree with you about Del Yocum’s nice sense of irony in offering Inprise’s Java tools to 
Microsoft the day after the judge ruled that Microsoft had to offer 100 percent pure Java in its 
products. It’s even more ironic than the idea of AOL, the pariah of the Web, buying Netscape, the 
company that created the Web.” 

“Don’t try to butter me up. You’re not a Swaine’s World employee, you don’t have an expense 
account, and I wouldn’t approve Cuba libres if you did.” 


“Fine, just run me a tab.” 
: 


Michael Swaine 
editor-at-large 
mswaine@swaine.com 
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Loaded with 
features... 


Multi - Language 
CodeBase 6.4 works with C, C++, Visual Basic, Delphi, ODBC 
and OLE DB. 





Incredible Speed 

Query a million records in 0.49 seconds. Append 10,000 
records in just 0.65 seconds! All this speed in a super- 
compact library that uses very little memory. 








Royalty Free 


Includes standalone, client and server. 





xBASE Compatible 


Multi-user file compatible with FoxPro, dBASE and Clipper 
data, index and memo files. 





Client/Server 

Advanced security features. New easy-to-use tools for 
monitoring database activity and managing user access. 
Incredibly easy installation and setup! 








Portable 
Runs under Windows 98, 95, NT, CE, 3.1, DOS, Mac, 05/2, Solaris, 
Sun0$, AIX, CO, Linux, UnixWare, DEC, Alpha, BSDI, HP/UX... 








wee Enterprise-Level Power 
Includes transaction processing, logging, backup and recovery 
tools, and intelligent queries. 








Say = And More.... 
PP For C, CH, Visual Basie and ; & - - 
ecole a te apm > Data-Aware controls, full-featured report writer and free 


technical support. Add-ons available for OLE DB, ODBC and 
Delphi BDE plug-in replacement. 





FREE 30 Day Test Drive 


Test drive the new CodeBase 6.4 for 30 days 
with your own code. No risk. No obligation. 
No royalties. Order today! 


. Call: 403-437-2410 


“CodeBase gives ACT! the fast database access 
that contact management users need.” 
- Michael Plasterer, Director of Development, Symantec 
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Web Site: www.sequiter.com 
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SEQUITER 
SOFTWARE INC. 


Award-Winning performance 5 years in a row! 
Fax: 403-436-2999 Email: info@sequiter.com 


© 1998 Sequiter Software Inc. All rights reserved. CodeBase and Sequiter are registered trademarks of Sequiter Software Inc. P.O. Box 783, Greenland, NH 
All other product names are trademarks of their respective companies. In Europe call: (44) 181-316-5001 
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rience the performance of a Java de\ 
ou do. Call Symantec today at (888) 82 


alCaté veri 


‘ks or registere trademarks of Sun Microsystems in the United States and other countries. Symantec and the Symantec 


of Symantec Corporation. In Canada, call 1-800-365-8641. In Australia, call 02-9850-1000. In jurope, call 


